fix(anti-debt): post-merge cleanup (dogfood, portability, contract drift)

.github/workflows/anti-debt-ci.yml

@@ -101,9 +101,8 @@ jobs:
         run: pip install ruff
       - name: Run scan quality test
         working-directory: stack/agents/anti-debt
-        run: |
-          # Tests corpus metrics — currently permissive thresholds (V1)
-          python3 tests/test_scan_quality.py || echo "[INFO] corpus tests are permissive in V1"
+        # Enforced: the test asserts recall >= 0.70 and precision >= 0.60.
+        run: python3 tests/test_scan_quality.py
 
   test-layer0-kg:
     name: Test Layer 0 (Knowledge Graph)

.gitignore

@@ -18,8 +18,10 @@ __pycache__/
 *.db
 *.log
 **/scan_periodic_report.json
+**/dashboard.html
 .debt-history.json
 .debt-scan.json
+calibration_report.md
 
 # Build artifacts (Rust test fixtures, etc.)
 **/target/

stack/agents/anti-debt/README.md

@@ -20,7 +20,7 @@ Cet agent détecte, classe, priorise et corrige la dette technique de manière :
 anti-debt/
 ├── AGENT.md                  # System prompt LLM-agnostique
 ├── taxonomy/
-│   └── debt-categories.yaml  # 4 catégories V1 (code, security, dependencies, tests)
+│   └── debt-categories.yaml  # 5 catégories (code, security, dependencies, tests, architecture)
 ├── schemas/
 │   ├── debt-finding.schema.json
 │   ├── debt-triage.schema.json   # sortie déterministe du Critic (tiers)

stack/agents/anti-debt/RECAP.md

@@ -14,15 +14,15 @@
 | Fichier | Rôle | Statut |
 |---------|------|--------|
 | `AGENT.md` | System prompt LLM-agnostique (6 directives anti-MVP) | ✅ |
-| `taxonomy/debt-categories.yaml` | 4 catégories × 20 sous-catégories | ✅ |
+| `taxonomy/debt-categories.yaml` | 5 catégories (code, security, dependencies, tests, architecture) | ✅ |
 | `schemas/debt-finding.schema.json` | Schéma finding avec evidence structurée | ✅ |
 | `schemas/debt-plan.schema.json` | Schéma plan avec critic_validation | ✅ |
 | `schemas/debt-history.schema.json` | Schéma historique persistant | ✅ |
 | `README.md` + `INSTALL.md` | Doc humain + procédure installation | ✅ |
 | `examples/` (3 fichiers) | Exemples validés JSON Schema | ✅ |
 | `adapters/generic/README.md` | Installation manuelle Codex/Aider | ✅ |
 
-**Validation** : taxonomie charge 4 catégories × 20 sous-catégories, 3 schémas JSON valides.
+**Validation** : taxonomie charge 5 catégories, 4 schémas JSON valides.
 
 ### Commit 2 — Skills Markdown ✅
 

stack/agents/anti-debt/adapters/claude-code/README.md

@@ -2,31 +2,37 @@
 
 ## Installation
 
-Dans ton projet, crée le dossier `.claude/skills/` et symlink :
+Lier le dossier **complet** `anti-debt` (PAS seulement `skills/`) — les scanners
+référencent `tools/` et `kg/` en relatif, donc lier `skills/` seul casse la
+résolution. `Path.resolve()` suit les liens, donc un lien/jonction du dossier
+entier fonctionne.
 
 ```bash
-# Depuis la racine de ton projet
-mkdir -p .claude/skills
-# Sur Windows (cmd ou PowerShell) :
-mklink /D .claude\skills\anti-debt ..\path\to\ai-native-dev-stack\stack\agents\anti-debt\skills
+# macOS / Linux
+ln -s /path/to/ai-native-dev-stack/stack/agents/anti-debt ~/.claude/skills/anti-debt
 
-# Ou copie si symlink indisponible
-cp -r ../path/to/ai-native-dev-stack/stack/agents/anti-debt/skills/* .claude/skills/anti-debt/
+# Windows (jonction — pas besoin d'admin) :
+#   New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\skills\anti-debt" `
+#            -Target "D:\path\to\ai-native-dev-stack\stack\agents\anti-debt"
 ```
 
 ## Activation
 
-Dans Claude Code :
+L'agent est un **agent** (system prompt + outils), pas un skill plat
+auto-découvert. Deux usages :
 
 ```
-/skill anti-debt:debt-scan
-```
-
-ou en début de session, mentionner l'AGENT.md :
+# 1. Charger le system prompt en début de session :
+@~/.claude/skills/anti-debt/AGENT.md
 
+# 2. Lancer un scan déterministe directement :
+python3 ~/.claude/skills/anti-debt/skills/debt-scan/tools/scan_code.py <repo>
+python3 ~/.claude/skills/anti-debt/tools/critic_v2.py score findings.json triage.json
 ```
-@.claude/skills/anti-debt/AGENT.md
-```
+
+> Note : `/skill anti-debt:debt-scan` ne fonctionne PAS — Claude Code découvre
+> les skills à plat (`~/.claude/skills/<nom>/SKILL.md`), or les skills de l'agent
+> sont imbriqués sous `skills/`. Réfère-les via `@` ou exécute les outils.
 
 ## Permissions recommandées
 

stack/agents/anti-debt/adapters/minimax-code/README.md

@@ -2,18 +2,26 @@
 
 ## Installation
 
-Dans ton projet, crée le dossier `.mavis/agents/` et copie les skills :
+Lier le dossier **complet** `anti-debt` (les scanners référencent `tools/` et
+`kg/` en relatif — lier `skills/` seul casserait la résolution) :
 
 ```bash
-mkdir -p .mavis/agents/
-ln -s ../../path/to/ai-native-dev-stack/stack/agents/anti-debt .mavis/agents/anti-debt
+mkdir -p ~/.mavis/agents
+# macOS / Linux
+ln -s /path/to/ai-native-dev-stack/stack/agents/anti-debt ~/.mavis/agents/anti-debt
+# Windows (jonction) :
+#   New-Item -ItemType Junction -Path "$env:USERPROFILE\.mavis\agents\anti-debt" `
+#            -Target "D:\path\to\ai-native-dev-stack\stack\agents\anti-debt"
 ```
 
 ## Activation
 
-Dans MiniMax Code, les skills sont auto-découverts si placés dans
-`.mavis/agents/<name>/skills/`. L'AGENT.md de l'agent `mavis` peut référencer
-ces skills via prompt système.
+Référencer `~/.mavis/agents/anti-debt/AGENT.md` dans le prompt système de
+l'agent `mavis`, puis exécuter les outils déterministes :
+
+```bash
+python3 ~/.mavis/agents/anti-debt/skills/debt-scan/tools/scan_code.py <repo>
+```
 
 ## Hooks custom Mavis recommandés
 

stack/agents/anti-debt/docs/v-max-design.md

@@ -148,7 +148,7 @@ L'agent vise une utilisation long terme (5+ ans sur un même projet) sans interv
 ### Layer 1 (Core) — V1 ✅
 
 - [x] AGENT.md LLM-agnostique
-- [x] Taxonomie extensible (4 catégories V1, extensions V2 commentées)
+- [x] Taxonomie extensible (5 catégories actives : code, security, dependencies, tests, architecture ; extensions V2 commentées)
 - [x] 3 schémas JSON Schema validés
 - [x] 8/8 tests unitaires verts
 

stack/agents/anti-debt/kg/AI_CONTEXT.md

@@ -0,0 +1,36 @@
+# AI_CONTEXT — anti-debt / kg
+
+## Purpose
+Layer 0: the **Knowledge Graph** (SQLite) — the source of truth for debt over
+time. Nodes (Component, Debt, Decision, Fix, Convention, ADR) and typed edges
+(causes, resolves, affects, supersedes, blocks, documents, conflicts) let the
+agent answer causal queries ("which debts affect X?", "what does this fix touch?").
+
+## Key files
+- `kg_schema.py` — `Node`/`Edge` dataclasses, SQL schema (WAL, FKs, indices),
+  migration registry. Validates types in `__post_init__`.
+- `kg_store.py` — `KgStore`: idempotent UPSERT CRUD (UNIQUE on node id and on
+  edge source+target+type).
+- `kg_query.py` — read-only causal queries; BFS traversals are cycle-guarded.
+- `kg_sync.py` — KG → Vault markdown snapshots + ADR import.
+- `kg_migrate.py` — V1 JSON (`.debt-scan`/`.debt-history`/`.debt-plan`) → V2 KG.
+
+## Constraints
+- **All ids must be deterministic** so re-runs are idempotent. `kg_migrate`
+  uses `_stable_hash` (hashlib), NEVER the builtin `hash()` (salted per process).
+- Upserts are idempotent by design — re-importing the same input is a no-op.
+- One canonical DB location: `kg/data/kg.db` (shared by `scan_periodic` and the
+  `registry` skill). Don't introduce a second path.
+
+## Forbidden
+- Never create self-loop edges (source == target) — the dataclass raises.
+- Never store a DebtTriage (`fix_order`) where a DebtPlan (`actions`) is expected;
+  `kg_migrate` guards against it (would silently record actions_count=0).
+
+## Common failure modes
+- Using builtin `hash()` for ids → cross-process non-idempotency (duplicate nodes).
+- Unbounded BFS on a `causes` cycle → guarded by the on-path check in `kg_query`.
+
+## See also
+- `../docs/adr/0023-storage-architecture-v2.md`, `../tools/scan_periodic.py`,
+  `../skills/debt-manage/tools/registry.py`.

stack/agents/anti-debt/skills/debt-architecture/tools/AI_CONTEXT.md

@@ -0,0 +1,29 @@
+# AI_CONTEXT — anti-debt / debt-architecture / tools
+
+## Purpose
+Architecture-level debt scanner: detects circular imports and high coupling
+across a Python repo. Backs the `debt-architecture` skill. Output conforms to
+`debt-finding.schema.json` (category `architecture`).
+
+## Key files
+- `scan_architecture.py` — `detect_circular_imports_repo` (DFS over the module
+  import graph) and `detect_high_coupling_python` (fan-out count).
+
+## Constraints
+- Cycle detection keeps the **full dotted module name** (not just the top-level
+  package) so nested-package cycles (`pkg.a <-> pkg.b`) are found, not only
+  root-level ones. Imports that don't resolve to a repo module are ignored.
+- Findings are heuristic → confidence `0.9` (never claim `1.0`).
+- Mint ids via `finding_common.finding_id` (imported from `../../../tools`).
+
+## Forbidden
+- Never raise `confidence` to 1.0 for these import-graph heuristics — they miss
+  dynamic imports and `from pkg import submodule` forms.
+
+## Common failure modes
+- `from pkg import sub` resolves `node.module` to `pkg`, which may not match the
+  `pkg.__init__` module key → some cycles via package `__init__` are missed (known).
+
+## See also
+- `../../debt-scan/tools/scan_deps.py` (also reports `dependencies/circular` for JS),
+  `../../../taxonomy/debt-categories.yaml` (architecture category).

stack/agents/anti-debt/skills/debt-manage/tools/AI_CONTEXT.md

@@ -0,0 +1,23 @@
+# AI_CONTEXT — anti-debt / debt-manage / tools
+
+## Purpose
+The Debt Registry CLI behind the `debt-manage` skill: CRUD over accepted/owned
+debts, persisted as `Debt` nodes in the Knowledge Graph (Layer 0). Commands:
+`register`, `update-status`, `query`, `assign`.
+
+## Key files
+- `registry.py` — argparse CLI; each command opens a `KgStore` and upserts.
+
+## Constraints
+- Default DB is the canonical `../../../kg/data/kg.db` (`DEFAULT_KG_DB`) — the
+  SAME database the scanners write to, so governance and detection share state.
+  Don't point it at a private path.
+- `register` requires a justification `reason` of ≥ 50 chars (anti "silent debt").
+- Status is one of `open | in_progress | accepted | resolved`.
+
+## Forbidden
+- Never write the registry to a second KG location (e.g. `~/.mavis/kg.db`) — it
+  would desync from the scanners' findings.
+
+## See also
+- `../../../kg/` (KgStore/Node), `../../../kg/AI_CONTEXT.md`.

stack/agents/anti-debt/skills/debt-prevention/tools/AI_CONTEXT.md

@@ -0,0 +1,28 @@
+# AI_CONTEXT — anti-debt / debt-prevention / tools
+
+## Purpose
+Turns recurring findings into prevention: generates linter/config rules and a
+regression guard so a fixed pattern cannot silently come back. Backs the
+`debt-prevention` skill.
+
+## Key files
+- `prevent_finding.py` — `aggregate_patterns` (group by category/subcategory,
+  threshold ≥ 3), `generate_rule` (emit a tool config from `RULE_TEMPLATES`),
+  `generate_regression_test` (emit a test asserting the rule stays in place).
+
+## Constraints
+- Config templates must be valid for their target tool (e.g. `ruff.toml` uses the
+  top-level `[lint]` schema, not `[tool.ruff]`).
+- Generated configs carry the `anti-debt-agent` marker so re-runs are idempotent
+  (append once) and the regression test can assert the guard's presence.
+
+## Forbidden
+- Never emit a tautological regression test (`assertTrue(True)`) — the generated
+  test must actually verify the prevention rule exists and is non-empty.
+
+## Common failure modes
+- A `(category, subcategory)` with no entry in `RULE_TEMPLATES` yields no rule —
+  `generate_regression_test` returns `None` rather than a fake passing test.
+
+## See also
+- `../../../docs/v-max-design.md` (Layer 6 — Prevention Generation).

stack/agents/anti-debt/skills/debt-scan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debt-scan
-description: Scan a codebase to detect technical debt (code, security, dependencies, tests). Orchestrate deterministic tools + LLM. Produce a `.debt-scan.json` file conforming to the schema.
+description: Scan a codebase to detect technical debt (code, security, dependencies, tests, architecture). Orchestrate deterministic tools + LLM. Produce a `.debt-scan.json` file conforming to the schema.
 license: MIT
 ---
 

stack/agents/anti-debt/skills/debt-scan/tools/AI_CONTEXT.md

@@ -0,0 +1,40 @@
+# AI_CONTEXT — anti-debt / debt-scan / tools
+
+## Purpose
+The deterministic scanners behind the `debt-scan` skill. Each detects one debt
+category and normalizes output to `debt-finding.schema.json`. They prefer real
+linters but degrade gracefully (warnings, not crashes) when a tool is absent.
+
+## Key files
+- `scan_code.py` — language detection + linter orchestration (ruff/clippy/eslint),
+  normalization, and `_augment_python` / `_augment_polyglot` post-processing.
+- `heuristic_scan.py` — pure-Python fallback (secrets, long funcs, dead imports,
+  duplication, coverage gaps); runs when the linter is missing + always for coverage.
+- `scan_security.py` — trufflehog / gitleaks / osv-scanner (secrets + known vulns).
+- `scan_deps.py` — cargo-audit / pip-audit / npm-audit / depcruise.
+- `aggregate.py` — merge per-tool outputs into one sorted `.debt-scan.json`.
+- `run_all.sh` — bash orchestrator with clean exit codes.
+
+## Constraints
+- Mint ids via `finding_common.finding_id(...)` (imported from `../../../tools`);
+  pass a stable `discriminator` when several findings share file+line+subcategory
+  (e.g. rule code, AST hash, import name) — otherwise they collide and dedup drops one.
+- `SECRET_PATTERNS` is centralized in `finding_common` — add a pattern ONCE there,
+  every scanner inherits it.
+- A missing external tool must return a `{"warning": ...}` entry, never raise.
+
+## Forbidden
+- Never silently narrow scope: a "complete" scan covers code+security+dependencies
+  (see `mvp_runtime` / `scan_periodic`). Skipping a category is the MVP bias the
+  agent exists to prevent.
+- Never emit a subcategory absent from `../../../taxonomy/debt-categories.yaml`.
+
+## Common failure modes
+- Secret detection only runs in the heuristic path (linter absent) — if ruff is
+  installed, provider-key detection comes from `scan_security` (trufflehog), not here.
+- On Windows + `shell=True`, a missing binary returns rc=1 (not FileNotFound) —
+  `run_scanner` does an explicit `shutil.which` check first.
+
+## See also
+- `../../../tools/finding_common.py`, `../../../taxonomy/debt-categories.yaml`,
+  `../../../tests/test_scan_quality.py`.

stack/agents/anti-debt/skills/debt-scan/tools/aggregate.py

@@ -7,6 +7,7 @@
 Usage:
     python3 aggregate.py .debt-scan-tmp/ [output.json]
 """
+from __future__ import annotations
 import json
 import sys
 import uuid