POLICIES - Wiederverwendbare Code-Standards
==========================================

Stand: 2026-01-23
Pfad: docs/help/tools/policies.txt

BESCHREIBUNG
------------
Policies sind wiederverwendbare Code-Snippets die BACH-Standards
durchsetzen. Sie werden in neue Projekte injiziert und sorgen für
konsistente Handhabung von:
  - Encoding (UTF-8, Windows-Console)
  - JSON (Emoji-safe, Encoding-Fallback)
  - Dateinamen (Praefix-Konvention)

SPEICHERORT
-----------
  tools/_policies/
    encoding_header.py    UTF-8 und Console-Fix
    emoji_safe.py         Emoji-Konvertierung
    json_safe.py          Sichere JSON-Operationen
    CONCEPT_naming_convention.md   Namenskonvention (Konzept)

VERFÜGBARE POLICIES
====================

1. encoding_header (v1.0)
-------------------------
UTF-8 Encoding Header und Windows Console Fix.
Wird am Dateianfang injiziert.

INJIZIERT:
  - Shebang: #!/usr/bin/env python3
  - Encoding: # -*- coding: utf-8 -*-
  - Windows Console Encoding Fix

TYPISCHER CODE:
  #!/usr/bin/env python3
  # -*- coding: utf-8 -*-

  import sys
  if sys.platform == 'win32':
      sys.stdout.reconfigure(encoding='utf-8', errors='replace')

2. emoji_safe (v1.0)
--------------------
Sichere Emoji-Handhabung für Speicherung/Transfer.

FUNKTIONEN:
  emoji_to_safe(text)      Emoji -> ASCII-safe (für DB/Files)
  emoji_to_display(text)   ASCII-safe -> Emoji (für Anzeige)

VERWENDUNG:
  from _policies.emoji_safe import emoji_to_safe
  safe_text = emoji_to_safe("Hello [TOOL]")  # -> "Hello :wrench:"

ABHAENGIGKEIT:
  Benötigt: pip install emoji (optional, graceful fallback)

3. json_safe (v1.0)
-------------------
Sichere JSON-Operationen mit Emoji/Encoding-Handling.

FUNKTIONEN:
  json_load_safe(filepath)       Lädt mit Encoding-Fallback
  json_save_safe(data, filepath) Speichert mit Emoji-Konvertierung
  json_dumps_safe(data)          Serialisiert ensure_ascii=False

VERWENDUNG:
  from _policies.json_safe import json_load_safe, json_save_safe

  # Laden (probiert utf-8, utf-8-sig, latin-1, cp1252)
  data = json_load_safe("config.json")

  # Speichern (konvertiert Emojis zu :shortcodes:)
  json_save_safe(data, "config.json", convert_emojis=True)

POLICY-FORMAT
=============
Jede Policy hat folgenden Aufbau:

  #!/usr/bin/env python3
  # -*- coding: utf-8 -*-
  """
  POLICY: name
  VERSION: 1.0
  SIZE: small/medium/large
  DESCRIPTION: Was macht die Policy
  """

  # === POLICY:name:version ===
  ... Code ...
  # === END:name ===

GROESENKLASSEN:
  small    -> Inline-Injection (wenige Zeilen)
  medium   -> Externe Datei (eigenes Modul)
  large    -> Mehrere Dateien

ATI PROJEKT-BOOTSTRAPPING
=========================
Policies werden vom ATI-Bootstrapper in neue Projekte injiziert:

  bach ati bootstrap my-tool --template python-cli

STANDARD-POLICIES für Python-CLI:
  - encoding_header (immer)
  - json_safe (wenn JSON verwendet)
  - emoji_safe (wenn Ausgabe an Console)

Siehe: agents/ati/ATI_PROJECT_BOOTSTRAPPING.md

NAMING CONVENTION (Konzept)
===========================
Geplante Namenskonvention für Tool-Dateien:

  c_  -> CLI-optimiert für AI (c_encoding_fixer.py)
  b_  -> BACH-Kern (b_backup.py)
  a_  -> Agent-Runner (a_entwickler.py)
  t_  -> Test-Tools (t_runner.py)
  m_  -> Maintain/Wartung (m_cleanup.py)
  g_  -> Generator-Tools (g_skill.py)

Status: KONZEPT - noch nicht implementiert
Siehe: tools/_policies/CONCEPT_naming_convention.md

EIGENE POLICY ERSTELLEN
=======================

1. Datei in tools/_policies/ erstellen
2. Policy-Header mit NAME, VERSION, SIZE, DESCRIPTION
3. Code zwischen # === POLICY:name:version === markieren
4. Optional: In project_bootstrapper.py registrieren

TYPISCHE ANWENDUNGSFAELLE
=========================

1. NEUES PYTHON-PROJEKT
   -> encoding_header automatisch injizieren

2. JSON-KONFIGURATION
   -> json_safe für sichere Speicherung

3. CONSOLE-AUSGABE MIT EMOJIS
   -> emoji_safe für Windows-Kompatibilität

4. BESTEHENDEN CODE STANDARDISIEREN
   -> c_standard_fixer nutzt Policies intern

SIEHE AUCH
----------
  bach --help tools/code_quality   Encoding/JSON-Fixer
  bach --help ati                  ATI Agent und Bootstrapping
  bach --help tools                Tool-Übersicht
