ellmos-ai · lukisch · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,15 @@
+# Normalize all text files to LF in the repository.
+# Without this, a checkout on Windows (core.autocrlf=true) and one on
+# Linux/macOS disagree about every text file, which shows up as a
+# whole-file diff ("phantom diff") that hides the real change.
+* text=auto eol=lf
+
+# Binary assets must never be touched by EOL normalization.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.woff binary
+*.woff2 binary
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -26,10 +26,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm

diff --git a/.gitignore b/.gitignore
@@ -18,4 +18,10 @@ Thumbs.db
 # Interne Multi-Agenten-Koordination (LOCK-System)
 LOCK*.txt
 
+# Interne Analyse-, Entscheidungs- und Pflegeunterlagen (nicht fuer Leser des Repos)
+docs/MEHRSPRACHIGKEIT-ANALYSE_*.md
+_after-care/
+AUFGABEN.txt
+BEFUNDE.md
+
 mobile_icons/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.25] - unreleased
+
+### Security
+- `@toon-format/toon` raised to `^2.3.1`, closing GHSA-p95v-992w-h6c3 (high: prototype pollution when decoding untrusted TOON input). TOON is an advertised input format of `cc_convert_format`, so this is on a path that takes untrusted input by design. Deliberately kept on the 2.x line — 2.3.1 closes the advisory, while the current `latest` (4.1.1) would mean two major jumps.
+- `qs` override raised to `^6.16.0` (GHSA-x5fp-wj9c-mxmx, GHSA-4mjr-xmp4-gh2g).
+- `fast-uri` override raised to `^3.1.7`, superseding Dependabot PR #10.
+- `npm audit` now reports 0 vulnerabilities (previously 1 high, 1 moderate).
+- CI actions pinned to commit SHAs (`actions/checkout` v7.0.1, `actions/setup-node` v7.0.0) instead of floating major tags.
+
+### Documentation accuracy
+- Removed the claim of **AST-based** class and method extraction from `README.md`, `README_de.md` and `llms.txt`. The static analysis is a line and pattern scanner — the source itself calls it an "AST-like parser" and the package carries no parsing dependency. A real `ast.parse` runs only as a Python subprocess gate before every `cc_python_structural_edit` apply, and inside `cc_runtime_import_diagnose`.
+- New section **Scope and limits** / **Geltungsbereich und Grenzen** in both READMEs, plus a scope note in `llms.txt`: which 9 of the 23 tools assume Python, that they do not currently validate the file extension (so non-Python input yields a plausible but wrong result instead of an error), and which two tools require a local `python` interpreter.
+- Fixed a broken list item in `llms.txt` (DokuReader used `|` instead of `:`).
+
+### Tests
+- Reversed three assertions in `test/metadata.test.ts` that pinned the current state instead of the property, and would each have blocked the very change they existed to encourage: the literal Vitest count `187` in the badge URL, the literal `Last-checked` date, and the literal `actions/*@v4` tags. They now check format, cross-surface consistency, and "tag or 40-character SHA".
+- `EXPECTED_TOOL_COUNT` is now counted from `src/index.ts` instead of being a hand-maintained constant.
+- Added a guard against the `AST-based` claim reappearing in the documentation surfaces.
+- Suite: 189 Vitest tests (was 187), 35 MCP stdio assertions, 43 i18n assertions — 267 total.
+
+### Repository hygiene
+- Added `.gitattributes` pinning text files to LF. Without it, a checkout on Linux or macOS reported all 40 tracked text files as fully changed.
+- Untracked `docs/MEHRSPRACHIGKEIT-ANALYSE_2026-08-25.md`: an internal decision paper, not user documentation, that exposed an internal ticket ID, a hostname, an absolute local path and the maintainer's local plugin setup.
+- Consolidated the three separate `[1.3.23]` headings below — see the note there.
+
 ## [1.3.24] - 2026-09-06
 
 ### Features & i18n Tool Surface
@@ -13,51 +38,55 @@ All notable changes to this project will be documented in this file.
 - Removed private repository link `dev-bricks/automation-master` from documentation and discovery indexes to prevent 404 dead links for external users.
 - Updated automated contract test suite in `test/metadata.test.ts` to assert 23 tools and verify exclusion of private repository links.
 
-## [1.3.23] - 2026-08-24
+## [1.3.23] - 2026-08-25
+
+> This heading previously appeared three times, dated 2026-08-24, 2026-08-21 and
+> 2026-08-16, which read as three releases of one version number. npm records a
+> single `1.3.23`, published 2026-08-25 — all three change sets shipped together in
+> that one release. The dates are kept below as work dates.
+>
+> Versions `1.3.19`, `1.3.20` and `1.3.21` exist on npm (all published 2026-07-31)
+> but have no entry in this file.
 
-### CI/CD Workflow Härtung & Multi-OS Matrix
+### 2026-08-24 — CI/CD Workflow Härtung & Multi-OS Matrix
 - Hardened GitHub Actions test workflow (`.github/workflows/tests.yml`) with a full multi-OS matrix (`ubuntu-latest`, `windows-latest`, `macos-latest`) across Node.js 20, 22, and 24.
 - Standardized action versions to `actions/checkout@v4` and `actions/setup-node@v4`.
 - Added workflow-level concurrency control (`group: ${{ github.workflow }}-${{ github.ref }}` with `cancel-in-progress: true`) to automatically cancel superseded workflow runs.
 
-### Automated Metadata & Contract Test Suite
+#### Automated Metadata & Contract Test Suite
 - Expanded contract test suite in `test/metadata.test.ts` to 15 tests (15/15 passed) covering multi-OS CI matrix declarations, concurrency configuration, package.json URLs and metadata integrity (`repository`, `bugs`, `homepage`, `type: module`), TypeScript strict compiler configuration (`tsconfig.json`), and package payload export lists.
 - Synchronized Shields.io test badge to `186 passed` Vitest tests and total 264 verified test assertions (186 Vitest unit tests, 35 MCP stdio integration tests, 43 i18n translation assertions).
 - Updated `llms.txt` discovery index with `Last-checked: 2026-08-24`, 264 verified test assertions, and multi-OS CI matrix documentation.
 
-## [1.3.23] - 2026-08-21
-
-### Discoverability & Documentation Architecture
+### 2026-08-21 — Discoverability & Documentation Architecture
 - Added second bilingual Mermaid sequence diagram (`Code Intelligence & Safe Structural Edit Lifecycle` / `Code-Intelligenz- und sicherer struktureller Edit-Lebenszyklus`) demonstrating client stdio JSON-RPC request flow, AST parsing, syntax validation, preview mode, and `.bak` backup creation.
 - Expanded Sibling Developer, File & Document Tools matrix across English and German READMEs (`README.md`, `README_de.md`) covering `DevCenter`, `CodeBox`, `MethodenAnalyser`, `PDFtoPDFocr`, `DokuReader`, `ProFiler`, `sqlite-transit-sync`, and `policy-registry`.
 - Synchronized Shields.io test badge to `183 passed` Vitest tests and total 261 verified test assertions (183 Vitest unit tests, 35 MCP stdio integration tests, 43 i18n translation assertions). Added Platform, Privacy, and Security badges.
 - Updated `llms.txt` discovery index with `Last-checked: 2026-08-21`, 261 verified test assertions, security invariants (Zero-Egress, Subprocess Isolation, Preview-Safe), and expanded sibling ecosystem references.
 
-### Security Policy Härtung (SECURITY.md)
+#### Security Policy Härtung (SECURITY.md)
 - Complete overhaul of `SECURITY.md` into a hardened bilingual (English / Deutsch) security policy document.
 - Formalized five core security invariants: Local-First Stdio Transport & Zero-Egress, Preview-First Structural Mutations (`mode: "preview"`, `.bak` backups), Non-Elevation User-Mode Execution, Input Boundary & Sanitization, and Subprocess Isolation for runtime import diagnostics (`cc_runtime_import_diagnose`).
 - Declared dedicated direct security contact channels (`security@ellmos.ai` and `support@lukasgeiger.com`) with 48h triage SLA alongside GitHub Security Advisories.
 
-### Automated Metadata & Contract Test Suite
+#### Automated Metadata & Contract Test Suite
 - Expanded `test/metadata.test.ts` to 12 contract tests (12/12 passed) validating CI matrix (`[20, 22, 24]`), bilingual security policy, authorized contact addresses, Mermaid diagrams in both READMEs, sibling tool references, and badge assertion parity across a full 183-test Vitest suite.
 
-## [1.3.23] - 2026-08-16
-
-### Security
+### 2026-08-16 — Security
 - Close the `js-yaml` advisory (quadratic CPU consumption in `!!omap` resolution, affecting 4.0.0-4.3.0) by raising the direct dependency to `^4.3.1`.
 - Close all open Dependabot advisories in lockfile (`ip-address`, `hono`, `fast-uri`, `nanoid`) — `npm audit` 100% clean.
 
-### Maintenance & Packaging
+#### Maintenance & Packaging
 - Realigned `glama.json`, `package.json`, `server.json`, `src/index.ts` to `1.3.23`.
 - Included `glama.json` and `smithery.yaml` in package files and registry triad.
 - Raised declared Node.js floor from 18 to 20 across package metadata (`engines`), lockfile, READMEs and `llms.txt` (`@hono/node-server` 2.x requirement).
 
-### Discoverability & Metadata Parity
+#### Discoverability & Metadata Parity
 - Synchronized Shields.io test badges across `README.md` and `README_de.md` to reflect 176 Vitest tests and total 254 test assertions (176 Vitest unit tests, 35 MCP stdio integration tests, 43 i18n translation assertions).
 - Expanded automated metadata test suite in `test/metadata.test.ts` (8/8 tests passed) validating manifest parity (`package.json`, `server.json`, `glama.json`, `src/index.ts`, `llms.txt`), presence of core documentation (`README.md`, `README_de.md`, `SECURITY.md`, `CHANGELOG.md`, `LICENSE`, `server.json`, `glama.json`, `llms.txt`), ecosystem & umbrella badges/links, and tool count assertions.
 - Updated `llms.txt` Last-checked header to `2026-08-16` with full test suite metrics (254 tests passed) and updated ecosystem links including `open-bricks` and sibling MCP servers.
 
-### Test Gates
+#### Test Gates
 - Added `npm run test:integration` for the 35 real MCP stdio assertions and `npm run test:i18n` for the 43 translation assertions; GitHub Actions now runs both alongside the Vitest gate on Node.js 20, 22 and 24.
 - Hardened the stdio harness so generated fixtures are removed on success, failures and termination, and the child process is terminated before the result is returned.
 

diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://img.shields.io/npm/v/ellmos-codecommander-mcp.svg)](https://www.npmjs.com/package/ellmos-codecommander-mcp)
 [![CodeCommander tests](https://github.com/ellmos-ai/ellmos-codecommander-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/ellmos-ai/ellmos-codecommander-mcp/actions/workflows/tests.yml)
-[![Vitest](https://img.shields.io/badge/Vitest-187%20passed-brightgreen.svg)](https://vitest.dev/)
+[![Vitest](https://img.shields.io/badge/Vitest-189%20passed-brightgreen.svg)](https://vitest.dev/)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://nodejs.org/)
 [![Privacy](https://img.shields.io/badge/Privacy-100%25%20Offline%20%7C%20Zero--Egress-success.svg)](SECURITY.md)
@@ -92,11 +92,11 @@ sequenceDiagram
     autonumber
     actor Developer as Developer / LLM Client
     participant Stdio as CodeCommander Server (stdio)
-    participant Core as AST & Code Intelligence Core
+    participant Core as Code Intelligence Core
     participant Disk as Local Filesystem
 
     Developer->>Stdio: cc_python_structural_edit (mode: "preview" / "apply")
-    Stdio->>Core: Parse Python AST & Validate Syntax
+    Stdio->>Core: Validate syntax via python -c "ast.parse(...)"
     alt Validation Failed
         Core-->>Stdio: Syntax / Parsing Diagnostics
         Stdio-->>Developer: Error Diagnostics & Line References
@@ -108,7 +108,7 @@ sequenceDiagram
             Stdio-->>Developer: Structural Diff Preview
         else Mode == "apply"
             Core->>Disk: Create .bak Backup File
-            Core->>Disk: Write Modified AST Code In-Place
+            Core->>Disk: Write Modified Source In-Place
             Core-->>Stdio: Confirmation with Applied Diff & Backup Path
             Stdio-->>Developer: Success Payload
         end
@@ -121,7 +121,7 @@ sequenceDiagram
 
 While FileCommander handles filesystem operations, CodeCommander focuses on **code intelligence**:
 
-- **Python Code Analysis** - AST-based class/method extraction, complexity metrics, import analysis
+- **Python Code Analysis** - class/method extraction, complexity metrics and import analysis, implemented as a dependency-free line and pattern scanner (see [Scope and limits](#scope-and-limits))
 - **BACH-derived Python Helpers** - runtime import diagnostics, structural edits, indentation checks, and template-based code generation
 - **JSON Repair** - Fix broken JSON automatically (trailing commas, single quotes, BOM, comments)
 - **Import Organization** - Sort and deduplicate Python imports per PEP 8
@@ -135,6 +135,33 @@ While FileCommander handles filesystem operations, CodeCommander focuses on **co
 
 ---
 
+## Scope and limits
+
+Being precise about this is more useful than a longer feature list:
+
+**The code-intelligence tools target Python.** Nine of the 23 tools — `cc_analyze_code`,
+`cc_analyze_methods`, `cc_extract_classes`, `cc_organize_imports`, `cc_diagnose_imports`,
+`cc_check_indentation`, `cc_generate_python_code`, `cc_runtime_import_diagnose` and
+`cc_python_structural_edit` — assume Python syntax. They currently do **not** check the file
+extension, so passing a `.ts` or `.js` file returns a plausible-looking but wrong result
+(typically zero classes and a misread import list) rather than an error. Until that guard
+exists, point them at Python files only. The other 14 tools (JSON, encoding, format
+conversion, diff, regex, Markdown export, language settings) are language-agnostic.
+
+**The analysis is a line and pattern scanner, not a Python AST parser.** It ships with no
+parsing dependency, which is why installation stays a single `npm install` with no native
+build step — but it also means deeply nested or multi-line constructs can be misread. Where a
+real parse matters it is used: `cc_python_structural_edit` runs
+`python -c "ast.parse(...)"` in a subprocess as a hard gate before any `apply`, and
+`cc_runtime_import_diagnose` executes imports in an isolated Python subprocess. Both therefore
+require a local `python` interpreter; the remaining tools do not.
+
+For semantic questions (type resolution, find-references, data flow) a language server such as
+Pyright is the right tool. CodeCommander deliberately stays on the structural and batch layer,
+reachable over MCP from any client without a project setup or a running server.
+
+---
+
 ## Installation
 
 ### Prerequisites
@@ -331,18 +358,18 @@ npm run test:i18n         # 43 translation assertions
 
 ### Testing
 
-The supported gates are deliberately separated: `npm test` runs the 187-test Vitest suite, `npm run test:integration` runs 35 real MCP stdio assertions against `dist/index.js`, and `npm run test:i18n` runs 43 translation assertions (265 automated test assertions total).
+The supported gates are deliberately separated: `npm test` runs the 189-test Vitest suite, `npm run test:integration` runs 35 real MCP stdio assertions against `dist/index.js`, and `npm run test:i18n` runs 43 translation assertions (267 automated test assertions total).
 
 ```bash
-npm test                  # Run Vitest unit tests (187 tests)
+npm test                  # Run Vitest unit tests (189 tests)
 npm run test:integration  # Real MCP stdio test (35 assertions, build first)
 npm run test:i18n         # i18n assertions (43 assertions)
 npm run test:all          # Run full test suite (build + vitest + integration + i18n)
 ```
 
 Tests are verified on **Windows**, **macOS**, and **Linux**.
 
-GitHub Actions runs the build, all three test gates (187 Vitest, 35 MCP stdio, 43 i18n assertions — 265 assertions total), and npm package check on Node.js 20, 22, and 24.
+GitHub Actions runs the build, all three test gates (189 Vitest, 35 MCP stdio, 43 i18n assertions — 267 assertions total), and npm package check on Node.js 20, 22, and 24.
 
 ---