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)