ki-manager 2.3.0.dev2__tar.gz → 2.3.1.dev1__tar.gz

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/.gitignore

@@ -29,3 +29,6 @@ posts/
 
 # Private plans (moved to KI-enterprise)
 plans/
+
+# Agent/MCP state
+.serena/

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/CHANGELOG.md

@@ -9,6 +9,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.1.dev1] — 2026-10-16
+
+### Security & Hardening
+- **Path Traversal Protection**: Enforced strict directory boundary containment across all file discovery and inspection tools (`find_unmapped_files`, `analyze_module`, `ki_search`, and custom agent paths) to prevent prefix-based sandbox traversal attacks.
+- **Secured Git Operations (`git_diff_secured`)**: Added hardened diff inspection tool protecting against flag injection (`--output`, etc.), shell command chaining, and repository boundary escapes.
+- **Restricted File Modifications**: Extended write protection to block direct modifications of shell/executable scripts (`.sh`, `.bash`, `.zsh`, `.js`, `.ts`, `.vbs`, `.wsf`) and internal system state files (`doc_config.json`, `ki_config.json`, `config.json`, `doc_state.json`) via direct file editing tools.
+
+### Changed
+- **Unified Tool Dispatch Schema**: In compact facade mode, dynamically bind `ki_call` and `ki_mutate` tool validation schemas (`enum` and `description`) directly to tool `readOnlyHint` annotations, eliminating dispatch conflicts and preventing model confusion.
+- **Date Format Resilience in `update_last_verified`**: Extended `update_last_verified` to automatically detect and update all supported date notation variants (HTML comment `<!-- last_verified: YYYY-MM-DD -->`, YAML frontmatter `last_verified: "YYYY-MM-DD"`, and Markdown bold `**Last verified**: YYYY-MM-DD`), and automatically insert the verification tag if missing.
+- **Workflow Instructions Alignment**: Synchronized tool arguments and signatures across `/expand-knowledge` and `/sync-knowledge` instructions, ensuring seamless execution in both compact facade and full tool modes.
+- **Daily MCP Log Rotation**: Server diagnostics now rotate daily (`mcp_YYYY-MM-DD.log`) with payload truncation to prevent runaway disk usage during high-frequency sessions.
+
+## [2.3.0] — 2026-10-11
+
+### Added
+- **Unified Cascade Path Resolution (`resolve_know_path`)**: `read_know_file`, `write_know_file`, and `edit_know_file` now share `ki_read`'s smart cascade resolver. AI agents can access and edit Knowledge Items using flat basenames (e.g. `KI_data_persistence.md`) without requiring explicit `knowledge/` directory prefixes.
+- **Smart Directory Placement for New KIs**: `write_know_file` now updates existing files in place across `knowledge/` rather than creating duplicates in the sandbox root, and automatically routes newly created flat KI files (`KI_*.md`, `*.ki.md`) into `<jail>/knowledge/`.
+- **ADR Name & Prefix Tolerance**: `resolve_know_path` and `ki_read` gracefully handle variations with or without `ADR_`/`adr_`/`ADR-` prefixes (e.g., resolving `ADR_002_node_status_queue_and_ui_feedback.md` to `002_node_status_queue_and_ui_feedback.md`) as well as numeric ADR IDs.
+- **Accurate Document Listings**: `get_ki_list_table()` dynamically reconciles registered entries in `doc_config.json` against filesystem reality, outputting exact on-disk filenames in document overviews.
+- **Comprehensive Project Overview**: `ki_instructions(document="knowledge-items")`, prompts, and `ki://knowledge-items.md` now present both Knowledge Items and Architecture Decision Records (ADRs) tables together when ADRs exist.
+
+### Highlights from 2.3.0 Development Cycle
+- Compact Facade Mode (`--tool-mode compact`) reducing MCP tools footprint from 34 schemas to 6 tools (`ki_instructions`, `ki_search`, `ki_read`, `ki_tools`, `ki_call`, `ki_mutate`), saving thousands of context tokens.
+- Native BM25 search engine (`ki_search`) with bilingual EN/RU stemming and field-weighted ranking.
+- Token-efficient reader with section filtering and character offset pagination (`ki_read`, `read_know_file`).
+- Batch ADR superseding (`create_adr`) with automatic status transitions, warning banners, git/environment snapshots, and quality sections (`rejected_alternatives`, `invariants`, `verification`).
+- Automated drift analysis (`check_ki_drift`) and Python AST pre-enrichment during scaffolding.
+
+### Added
+- `create_adr` batch `supersedes` support: accept a list of previous ADR IDs (`supersedes: ["001", "002"]`) to supersede multiple older records simultaneously; automatically updates deprecated ADR files with warning banners and `Superseded by ADR XXX` statuses, updates `doc_config.json`, and embeds bi-directional cross-links in the generated ADR.
+- Automated contextual provenance in `create_adr`: deterministically captures Git HEAD commit hash, current branch, and author, as well as an environment snapshot (operating system, Python runtime, and `ki-manager` version) without LLM overhead or prompt tokens.
+- Automated Scope & Knowledge Graph linking in `create_adr`: automatically discovers modified project files from Git or accepts explicit `affected_files`, correlates them with Knowledge Items in `doc_config.json`, and records them in the ADR's `depends_on` dependencies list.
+- Structured ADR quality sections: added support for `rejected_alternatives` (documenting abandoned paths and failed attempts to prevent regression loops), `invariants` (enforceable MUST / MUST NOT rules for future AI sessions), and `verification` (automated test commands or validation checklists).
+- `check_ki_drift` MCP tool & CLI script: automated discrepancy detection between Knowledge Items and the codebase, flagging dead symbols, unmapped public symbols, missing `depends_on` files, broken `[[KI_*.md]]` wiki-links, and Git date discrepancies against `last_verified`.
+- AST pre-enrichment in `generate_ki_scaffolds`: parses Python AST to pre-populate module docstrings into `## Overview`, class/function docstrings into the `Key Components` table, signatures, detected environment variables, and discovered test commands from `tests/`.
+- Canonical KI template featuring `## Entry Points & Public API` and `## Testing & Verification` sections, along with an updated canonical ADR template.
+- Integrated `check_ki_drift` into the `/sync-knowledge` workflow and the `coverage_analysis` tool group in facade mode.
+
+### Changed
+- Updated `/create-adr` workflow instructions and tool schemas with the new ADR parameters across both full and compact tool modes.
+- Aligned KI structures across `scaffold-knowledge.md`, `expand-knowledge.md`, `sync-knowledge.md`, and scaffold generators to the canonical template.
+- Made `finalize_ki_scaffolds` summary extraction resilient and backwards-compatible with legacy `## Purpose` and `## What it Does` headers.
+- Cleaned up duplicate local `knowledge/KI_template.md` in favor of package template.
+
 ## [2.3.0.dev2] — 2026-10-06
 
 ### Added

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ki-manager
-Version: 2.3.0.dev2
+Version: 2.3.1.dev1
 Summary: Knowledge Item (KI) management MCP server for AI-assisted development
 Project-URL: Homepage, https://github.com/Laeryid/KI-base
 Project-URL: Repository, https://github.com/Laeryid/KI-base
@@ -82,7 +82,10 @@ It provides:
    {
      "mcpServers": {
        "ki-manager": {
-         "command": "ki-manager"
+         "command": "ki-manager",
+         "args": ["--tool-mode", "compact"],
+         "directTools": true,
+         "lifecycle": "eager"
        }
      }
    }

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/README.md

@@ -37,7 +37,10 @@ It provides:
    {
      "mcpServers": {
        "ki-manager": {
-         "command": "ki-manager"
+         "command": "ki-manager",
+         "args": ["--tool-mode", "compact"],
+         "directTools": true,
+         "lifecycle": "eager"
        }
      }
    }

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ki-manager"
-version = "2.3.0.dev2"
+version = "2.3.1.dev1"
 description = "Knowledge Item (KI) management MCP server for AI-assisted development"
 readme = "README.md"
 license = { file = "LICENSE" }

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/src/ki_manager/__init__.py

@@ -1,3 +1,3 @@
 
 """ki-manager — Knowledge Item MCP server for AI-assisted development."""
-__version__ = "2.3.0.dev2"
+__version__ = "2.3.1.dev1"

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/src/ki_manager/cli.py

@@ -20,10 +20,10 @@ _WORKFLOWS_DIR = _PACKAGE_DIR / "workflows"
 
 
 def _parse_frontmatter(text: str) -> tuple[dict, str]:
-    """Парсит YAML frontmatter из маркдаун-файла.
+    """Parses YAML frontmatter from a markdown file.
     
-    Возвращает (meta_dict, body_text).
-    Если frontmatter нет — возвращает ({}, text).
+    Returns (meta_dict, body_text).
+    If there is no frontmatter, returns ({}, text).
     """
     if not text.startswith("---"):
         return {}, text

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/analyze_module.py

@@ -4,7 +4,7 @@ import argparse
 import io
 from typing import Dict, List, Optional
 
-# Добавляем путь к скриптам, чтобы импортировать ki_utils
+# Add path to scripts to import ki_utils
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import ki_utils
 
@@ -17,7 +17,7 @@ def format_size(size_bytes: int) -> str:
         return f"{size_bytes / (1024 * 1024):.2f} MB"
 
 def get_tracked_files(config: Dict) -> Dict[str, str]:
-    """Возвращает мапу {путь_к_файлу: имя_KI}"""
+    """Returns a map {file_path: KI_name}"""
     tracked = {}
     ki_items = config.get("knowledge_items", {})
     for ki_name, ki_data in ki_items.items():
@@ -30,8 +30,11 @@ def analyze_path(target_path: str, recursive: bool = False):
     config = ki_utils.get_doc_config()
     tracked_map = get_tracked_files(config)
     
-    # Резолвим абсолютный путь
+    # Resolve absolute path
     abs_target = os.path.normpath(os.path.join(project_root, target_path))
+    if not ki_utils.is_subpath(abs_target, project_root):
+        print(f"Error: Path '{target_path}' escapes project root.")
+        return
 
     if not os.path.exists(abs_target):
         print(f"Error: Path {target_path} not found.")
@@ -87,7 +90,7 @@ def analyze_path(target_path: str, recursive: bool = False):
             continue
 
 def main():
-    # Исправление кодировки для Windows при прямом запуске
+    # Fix encoding for Windows when run directly
     if sys.platform == "win32":
         import io
         sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/audit_coverage.py

@@ -65,7 +65,7 @@ def load_ki_files() -> list:
     ki_dir = os.path.join(get_knowledge_root(), "knowledge")
     if not os.path.isdir(ki_dir):
         return []
-    return [f for f in os.listdir(ki_dir) if f.startswith("KI_") and f.endswith(".md")]
+    return [f for f in os.listdir(ki_dir) if ki_utils.is_ki_filename(f)]
 
 
 # ─── Metrics ──────────────────────────────────────────────────────────────────

ki_manager-2.3.1.dev1/src/ki_manager/scripts/check_ki_drift.py

@@ -0,0 +1,382 @@
+"""
+check_ki_drift.py
+
+Detects discrepancies (drift) between Knowledge Items (KI) and the actual codebase:
+1. Symbol Drift:
+   - Dead symbols in Key Components table (deleted/renamed in code).
+   - Unmapped public symbols in source files (new code not yet in KI).
+2. File Drift:
+   - Broken or missing file paths in doc_config.json depends_on.
+3. Date Drift:
+   - Source files modified in git after KI's <!-- last_verified: YYYY-MM-DD -->.
+4. Broken Wiki-links:
+   - [[Target_KI.md]] links in Related KIs that do not exist.
+5. Integrity Drift:
+   - Pending scaffolds (<!-- scaffold: true -->) or remaining <!-- TODO --> markers.
+
+Usage:
+    python check_ki_drift.py --all
+    python check_ki_drift.py --ki KI_server.md
+    python check_ki_drift.py --json
+"""
+
+import os
+import sys
+import re
+import json
+import argparse
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional, Any, Set
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ki_utils
+from generate_ki_scaffolds import extract_symbol_details
+
+
+def parse_ki_file(ki_path: Path) -> Dict[str, Any]:
+    """Parse a KI markdown file and extract its metadata, tables, and links."""
+    try:
+        content = ki_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return {
+            "error": f"Cannot read {ki_path.name}",
+            "last_verified": None,
+            "is_scaffold": False,
+            "is_enriched": False,
+            "has_todo": False,
+            "table_symbols": [],
+            "wiki_links": [],
+            "sections": set(),
+        }
+
+    lines = content.splitlines()
+    last_verified = None
+    is_scaffold = False
+    is_enriched = False
+    has_todo = "<!-- TODO" in content or "TODO:" in content
+
+    # Check top lines for markers
+    for line in lines[:5]:
+        line_clean = line.strip()
+        if "<!-- scaffold: true -->" in line_clean:
+            is_scaffold = True
+        elif "<!-- scaffold: enriched -->" in line_clean:
+            is_enriched = True
+        elif line_clean.startswith("<!-- last_verified:"):
+            parts = line_clean.split(":", 1)
+            if len(parts) > 1:
+                last_verified = parts[1].replace("-->", "").strip()
+
+    # Extract sections
+    sections = set()
+    for line in lines:
+        if line.startswith("## "):
+            sections.add(line[3:].strip())
+
+    # Extract Key Components table symbols
+    # Expected table format: | `SymbolName` | `rel/path/file.ext` | Purpose |
+    table_symbols: List[Dict[str, str]] = []
+    in_key_components = False
+    table_row_pattern = re.compile(r"\|\s*`?([A-Za-z0-9_]+)`?\s*\|\s*`?([^`|\s]+)`?\s*\|")
+
+    for line in lines:
+        if line.startswith("## Key Components"):
+            in_key_components = True
+            continue
+        elif in_key_components and line.startswith("## "):
+            in_key_components = False
+            continue
+
+        if in_key_components and line.strip().startswith("|"):
+            lower = line.lower()
+            if any(k in lower for k in ["class / function", "component", "|---", "|:---", "| — |", "| - |"]):
+                continue
+            m = table_row_pattern.search(line)
+            if m:
+                sym_name = m.group(1).strip()
+                file_rel = m.group(2).strip()
+                header_keywords = {"component", "file", "purpose", "class", "function", "description"}
+                if sym_name.lower() in header_keywords or file_rel.lower() in header_keywords:
+                    continue
+                if sym_name and file_rel and not file_rel.startswith("—"):
+                    table_symbols.append({"symbol": sym_name, "file": file_rel})
+
+    # Extract wiki-links [[KI_*.md]]
+    wiki_links = []
+    for link_match in re.finditer(r"\[\[([^\]]+)\]\]", content):
+        wiki_links.append(link_match.group(1).strip())
+
+    return {
+        "last_verified": last_verified,
+        "is_scaffold": is_scaffold,
+        "is_enriched": is_enriched,
+        "has_todo": has_todo,
+        "table_symbols": table_symbols,
+        "wiki_links": wiki_links,
+        "sections": sections,
+    }
+
+
+def get_git_commit_date(project_root: str, rel_path: str) -> Optional[str]:
+    """Returns the ISO date (YYYY-MM-DD) of the last git commit touching rel_path."""
+    try:
+        res = subprocess.run(
+            ["git", "log", "-1", "--format=%cs", "--", rel_path],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=5,
+        )
+        if res.returncode == 0:
+            date_str = res.stdout.strip()
+            return date_str if date_str else None
+    except Exception:
+        pass
+    return None
+
+
+def check_single_ki(
+    ki_name: str,
+    ki_path: Path,
+    doc_config: dict,
+    project_root: str,
+    knowledge_dir: Path
+) -> Dict[str, Any]:
+    """Inspects a single KI file against code and configuration for drift."""
+    ki_data = parse_ki_file(ki_path)
+    if "error" in ki_data:
+        return {"ki": ki_name, "error": ki_data["error"], "drift_count": 1}
+
+    config_entry = doc_config.get("knowledge_items", {}).get(ki_name, {})
+    depends_on = config_entry.get("depends_on", [])
+
+    dead_symbols: List[Dict[str, str]] = []
+    unmapped_symbols: List[Dict[str, Any]] = []
+    missing_files: List[str] = []
+    date_drifts: List[Dict[str, str]] = []
+    broken_links: List[str] = []
+    integrity_issues: List[str] = []
+
+    # 1. Integrity issues
+    if ki_data["is_scaffold"]:
+        integrity_issues.append("Scaffold stub is still pending (<!-- scaffold: true -->)")
+    elif ki_data["is_enriched"]:
+        integrity_issues.append("Scaffold is enriched but not finalized (run ki_finalize_scaffolds)")
+    if ki_data["has_todo"]:
+        integrity_issues.append("Contains unpopulated <!-- TODO --> markers")
+
+    # 2. Check depends_on files existence
+    for dep in depends_on:
+        dep_path = Path(project_root) / dep
+        if not dep_path.exists():
+            missing_files.append(dep)
+
+    # 3. Check wiki-links
+    for link in ki_data["wiki_links"]:
+        # Standardize target name
+        target_name = link if link.endswith(".md") else f"{link}.md"
+        target_path = knowledge_dir / target_name
+        if not target_path.exists():
+            broken_links.append(link)
+
+    # 4. Group table symbols by file to check symbol drift
+    symbols_by_file: Dict[str, Set[str]] = {}
+    for entry in ki_data["table_symbols"]:
+        f_norm = entry["file"].replace("\\", "/")
+        symbols_by_file.setdefault(f_norm, set()).add(entry["symbol"])
+
+    # Determine files to inspect for symbol drift
+    files_to_inspect = set(symbols_by_file.keys())
+    for dep in depends_on:
+        dep_norm = dep.replace("\\", "/")
+        dep_abs = Path(project_root) / dep
+        if dep_abs.is_file() and dep_abs.suffix.lower() in (".py", ".ts", ".tsx", ".js", ".jsx", ".go"):
+            files_to_inspect.add(dep_norm)
+
+    for rel_file in files_to_inspect:
+        abs_file = Path(project_root) / rel_file
+        if not abs_file.exists():
+            if rel_file not in missing_files:
+                missing_files.append(rel_file)
+            continue
+
+        # Extract real symbols from code
+        code_details = extract_symbol_details(str(abs_file))
+        code_symbols_dict = {s["name"]: s for s in code_details.get("symbols", [])}
+        code_symbols_set = set(code_symbols_dict.keys())
+
+        # Check dead symbols (present in KI table, absent in code)
+        documented_symbols = symbols_by_file.get(rel_file, set())
+        for doc_sym in documented_symbols:
+            if doc_sym not in code_symbols_set:
+                dead_symbols.append({"symbol": doc_sym, "file": rel_file})
+
+        # Check unmapped public symbols in source files
+        # (Only report top-level non-private symbols)
+        for sym_name, sym_info in code_symbols_dict.items():
+            if sym_name not in documented_symbols and not sym_name.startswith("_"):
+                unmapped_symbols.append({
+                    "symbol": sym_name,
+                    "kind": sym_info.get("kind", "symbol"),
+                    "file": rel_file,
+                })
+
+        # Check date drift if last_verified is present
+        if ki_data["last_verified"]:
+            last_commit_date = get_git_commit_date(project_root, rel_file)
+            if last_commit_date and last_commit_date > ki_data["last_verified"]:
+                date_drifts.append({
+                    "file": rel_file,
+                    "commit_date": last_commit_date,
+                    "last_verified": ki_data["last_verified"],
+                })
+
+    drift_count = (
+        len(dead_symbols)
+        + len(unmapped_symbols)
+        + len(missing_files)
+        + len(date_drifts)
+        + len(broken_links)
+        + len(integrity_issues)
+    )
+
+    return {
+        "ki": ki_name,
+        "drift_count": drift_count,
+        "last_verified": ki_data["last_verified"],
+        "dead_symbols": dead_symbols,
+        "unmapped_symbols": unmapped_symbols,
+        "missing_files": missing_files,
+        "date_drifts": date_drifts,
+        "broken_links": broken_links,
+        "integrity_issues": integrity_issues,
+    }
+
+
+def run_drift_check(
+    ki_filter: Optional[str] = None,
+    project_root: Optional[str] = None,
+    knowledge_root: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Runs drift check on one or all KIs."""
+    if not project_root:
+        project_root = ki_utils.get_project_root()
+    if not knowledge_root:
+        knowledge_root = ki_utils.get_knowledge_root()
+
+    if not knowledge_root or not project_root:
+        raise RuntimeError("Could not determine project root or knowledge root.")
+
+    knowledge_dir = Path(knowledge_root) / "knowledge"
+    if not knowledge_dir.exists() and Path(knowledge_root).exists():
+        knowledge_dir = Path(knowledge_root)
+
+    if not knowledge_dir.exists():
+        return []
+
+    doc_config = ki_utils.get_doc_config()
+
+    if ki_filter:
+        target_name = ki_filter if ki_filter.endswith(".md") else f"{ki_filter}.md"
+        target_path = knowledge_dir / target_name
+        if not target_path.exists():
+            return [{"ki": target_name, "error": f"File not found: {target_name}", "drift_count": 1}]
+        return [check_single_ki(target_name, target_path, doc_config, project_root, knowledge_dir)]
+
+    results = []
+    for f in sorted(f for f in knowledge_dir.glob("*.md") if ki_utils.is_ki_filename(f.name)):
+        results.append(check_single_ki(f.name, f, doc_config, project_root, knowledge_dir))
+
+    return results
+
+
+def format_drift_markdown(results: List[Dict[str, Any]]) -> str:
+    """Formats drift check results as clean Markdown."""
+    total_kis = len(results)
+    with_drift = [r for r in results if r.get("drift_count", 0) > 0]
+
+    lines = [
+        f"### Knowledge Base Drift Report",
+        f"- **Checked KIs**: {total_kis}",
+        f"- **KIs with drift**: {len(with_drift)}",
+        "",
+    ]
+
+    if not with_drift:
+        lines.append("✅ **No drift detected.** All Knowledge Items match current code and git state.")
+        return "\n".join(lines)
+
+    for item in with_drift:
+        ki_name = item["ki"]
+        lines.append(f"#### ⚠️ `{ki_name}` ({item['drift_count']} issues)")
+
+        if item.get("error"):
+            lines.append(f"- [!] Error: {item['error']}")
+            continue
+
+        for issue in item.get("integrity_issues", []):
+            lines.append(f"- [!] **Integrity**: {issue}")
+
+        for dead in item.get("dead_symbols", []):
+            lines.append(f"- [!] **Dead symbol**: `{dead['symbol']}` (no longer in `{dead['file']}`)")
+
+        for missing in item.get("missing_files", []):
+            lines.append(f"- [!] **Missing file**: `{missing}` (does not exist on disk)")
+
+        for broken in item.get("broken_links", []):
+            lines.append(f"- [!] **Broken wiki-link**: `[[{broken}]]` (target KI does not exist)")
+
+        for date_item in item.get("date_drifts", []):
+            lines.append(
+                f"- [~] **Date drift**: `{date_item['file']}` was committed on "
+                f"`{date_item['commit_date']}`, after last_verified (`{date_item['last_verified']}`)"
+            )
+
+        unmapped = item.get("unmapped_symbols", [])
+        if unmapped:
+            sample = unmapped[:5]
+            more = len(unmapped) - 5
+            unmapped_str = ", ".join(f"`{u['symbol']}`" for u in sample)
+            if more > 0:
+                unmapped_str += f" and {more} more"
+            lines.append(f"- [+] **Unmapped symbols**: {unmapped_str} in `{unmapped[0]['file']}`")
+
+        lines.append("")
+
+    return "\n".join(lines).strip()
+
+
+def main():
+    if sys.platform == "win32":
+        sys.stdout.reconfigure(encoding="utf-8")
+
+    parser = argparse.ArgumentParser(description="Check drift and discrepancies between KI files and codebase.")
+    parser.add_argument("--ki", type=str, help="Specific KI file to check (e.g. KI_server.md)")
+    parser.add_argument("--all", action="store_true", help="Check all KIs in the knowledge base")
+    parser.add_argument("--json", action="store_true", help="Output results in JSON format")
+    parser.add_argument("--workspace", type=str, default=None, help=argparse.SUPPRESS)
+
+    args = parser.parse_args()
+
+    if args.workspace:
+        ki_utils.ACTIVE_WORKSPACE_PATH = ki_utils.normalize_path(args.workspace)
+    else:
+        match = ki_utils.find_project_by_cwd(os.getcwd())
+        if match:
+            target_path = match.get("config_path") or match.get("workspace") or os.getcwd()
+            ki_utils.ACTIVE_WORKSPACE_PATH = ki_utils.normalize_path(target_path)
+        else:
+            ki_utils.ACTIVE_WORKSPACE_PATH = ki_utils.normalize_path(os.getcwd())
+
+    results = run_drift_check(ki_filter=args.ki)
+
+    if args.json:
+        print(json.dumps(results, indent=2, ensure_ascii=False))
+    else:
+        print(format_drift_markdown(results))
+
+
+if __name__ == "__main__":
+    main()

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/finalize_ki_scaffolds.py

@@ -29,8 +29,8 @@ PENDING_MARKER = "<!-- scaffold: true -->"
 
 
 def extract_overview(content: str) -> str:
-    """Extract the first non-empty paragraph from the Overview section."""
-    match = re.search(r"## Overview\s*\n(.*?)(?=\n##|\Z)", content, re.DOTALL)
+    """Extract the first non-empty paragraph from the Overview section (or legacy Purpose / What it Does)."""
+    match = re.search(r"## (?:Overview|Purpose|What it Does)\s*\n(.*?)(?=\n##|\Z)", content, re.DOTALL)
     if not match:
         return ""
     text = match.group(1).strip()
@@ -70,7 +70,7 @@ def finalize_scaffolds(dry_run: bool = False) -> None:
     skipped_clean = 0
 
     for fname in sorted(os.listdir(ki_dir)):
-        if not (fname.startswith("KI_") and fname.endswith(".md")):
+        if not ki_utils.is_ki_filename(fname):
             continue
 
         ki_path = os.path.join(ki_dir, fname)

{ki_manager-2.3.0.dev2 → ki_manager-2.3.1.dev1}/src/ki_manager/scripts/find_unmapped_files.py

@@ -5,7 +5,7 @@ import json
 from pathlib import Path
 from typing import List
 
-# Добавляем путь к ki_utils
+# Add path to ki_utils
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import ki_utils
 
@@ -17,7 +17,7 @@ def get_unmapped_files(target_path: str = ".") -> List[str]:
     if not project_root or not doc_config:
         return []
 
-    # 1. Собираем все файлы, которые уже замаплены в doc_config.json
+    # 1. Collect all files that are already mapped in doc_config.json
     mapped_paths = set()
     knowledge_items = doc_config.get("knowledge_items", {})
 
@@ -27,8 +27,10 @@ def get_unmapped_files(target_path: str = ".") -> List[str]:
             abs_p = os.path.abspath(os.path.join(project_root, p))
             mapped_paths.add(abs_p)
 
-    # 2. Сканируем целевую директорию
+    # 2. Scan the target directory
     abs_target = os.path.abspath(os.path.join(project_root, target_path))
+    if not ki_utils.is_subpath(abs_target, project_root):
+        return []
     if not os.path.exists(abs_target):
         return []