May 27, 2026, 9:48 AM

2026-05-27 07:48:02 +00:00
parent 2d40028939
commit 405d42209c
28 changed files with 0 additions and 0 deletions
@@ -0,0 +1,174 @@
+Poniżej masz **konkretny, README‑ready opis HOOK‑a typu `command‑logger`**, dopasowany do Twojego stylu operacyjnego (OpenClaw / org‑mode / „plaintext productivity”). To **opis projektowy + kontrakt**, nie marketing.
+
+***
+
+# HOOK: `command-logger`
+
+## Cel
+
+`command-logger` to **globalny hook obserwacyjny**, który **rejestruje każde polecenie / wywołanie SKILL‑a** wraz z kontekstem wykonania, **bez wpływu na logikę biznesową**.  
+Jego jedyną odpowiedzialnością jest **audit trail** i **rekonstrukcja przebiegu pracy**.
+
+> To jest odpowiednik `bash history + strace + journalctl`, ale na poziomie **AI / SKILL routera**.
+
+***
+
+## Miejsce w architekturze
+
+*   typ: **HOOK (side‑effect only)**
+*   moment: **BEFORE + AFTER execution**
+*   zasięg: **router + wszystkie sub‑skills**
+*   brak modyfikacji danych wejściowych/wyjściowych
+
+<!---->
+
+    User → Router
+            ↳ HOOK: command-logger (BEFORE)
+            → Skill / Sub-skill
+            ↳ HOOK: command-logger (AFTER)
+
+***
+
+## Co jest logowane (kontrakt)
+
+### 1. Metadane techniczne
+
+*   `timestamp_start`
+*   `timestamp_end`
+*   `duration_ms`
+*   `session_id`
+*   `trace_id`
+*   `parent_trace_id`
+*   `host` / `agent_id`
+
+### 2. Kontekst wykonania
+
+*   `actor` (user / system / agent)
+*   `skill_name`
+*   `skill_version`
+*   `hook_phase` (`before` | `after`)
+*   `stage` (np. Inicjacja / Badania / Transakcja)
+*   `intent` (jeśli wykryty przez router)
+
+### 3. Dane operacyjne (bezpieczne)
+
+*   `command` – **skrót/identyfikator**, nie pełny prompt
+*   `input_fingerprint` (hash / checksum)
+*   `output_fingerprint`
+*   `status` (`ok` | `error`)
+*   `error_type` (jeśli wystąpił)
+
+> **Zasada**: logujemy **fakty o operacji**, nie jej treść semantyczną.
+
+***
+
+## Format zapisu (org‑mode friendly)
+
+### Jeden plik = jeden strumień pracy
+
+`command-log.org`
+
+```org
+* 2026-03-16 09:12:04 | router
+:PROPERTIES:
+:session: 9f3a…
+:trace:   r-001
+:phase:   before
+:actor:   user
+:stage:   Badania
+:intent:  seo-research
+:END:
+Command: route → seo-research
+Input:  sha256:8ac7…
+```
+
+```org
+* 2026-03-16 09:12:18 | seo-research
+:PROPERTIES:
+:session: 9f3a…
+:trace:   r-001
+:parent:  r-000
+:phase:   after
+:status:  ok
+:duration_ms: 14231
+:END:
+Output: sha256:91bd…
+```
+
+✅ spełnia:
+
+*   plaintext
+*   diff‑friendly
+*   audytowalne
+*   nadaje się do grep / ripgrep / org‑agenda
+
+***
+
+## Zasady projektowe (ważne)
+
+### ✅ Co `command-logger` MOŻE
+
+*   rejestrować
+*   tagować
+*   agregować
+*   eksportować (np. do Splunk / JSONL)
+
+### ❌ Czego NIE MOŻE
+
+*   zmieniać inputu
+*   zmieniać outputu
+*   blokować wykonania
+*   podejmować decyzji
+
+> Jeśli HOOK zaczyna „myśleć” → to **nie jest już hook**, tylko policy‑engine.
+
+***
+
+## Przykładowa definicja (konceptualna)
+
+```yaml
+hook:
+  name: command-logger
+  type: observer
+  phases: [before, after]
+  scope: global
+  output:
+    format: org
+    file: command-log.org
+  privacy:
+    log_payload: false
+    use_fingerprints: true
+```
+
+***
+
+## Typowe use‑case’y
+
+*   ✅ **rekonstrukcja dnia pracy** („co robiłem i dlaczego”)
+*   ✅ **debug AI** (gdzie poszło nie tak)
+*   ✅ **time audit** pod książkę o produktywności
+*   ✅ **compliance / audit trail**
+*   ✅ **trening systemu** (analiza sekwencji, nie treści)
+
+***
+
+## Anty‑wzorce
+
+❌ logowanie pełnych promptów  
+❌ logowanie danych wrażliwych  
+❌ zależność innych SKILL‑i od loggera  
+❌ brak identyfikatorów sesji / trace
+
+***
+
+## TL;DR (jednym zdaniem)
+
+> **`command-logger` to czarny skrzynkowy rejestr zdarzeń**, który zapisuje *że coś się stało, kiedy, gdzie i z jakim skutkiem* — **bez ingerencji w to, co i dlaczego**.
+
+***
+
+Jeśli chcesz, w kolejnym kroku mogę:
+
+*   dodać **diagram Mermaid tylko dla HOOK‑ów**
+*   rozpisać **drugiego hooka**: `decision-logger` (tylko dla routera)
+*   albo przygotować **OpenClaw SKILL: hooks/command-logger** (router + middleware)