Skip to content

Commit b6ac8be

Browse files
Delqhiv0 agent (Delqhi)
andauthored
docs(SR-187): AGENTS.md datetime hygiene section
Closes the last open acceptance item from #186: - [ ] Docs: AGENTS.md 'datetime hygiene' section What was added -------------- 1. Step 3 of ARCHÄOLOGIE-TSUNAMI's BANNED-Patterns list now mentions datetime.utcnow() with a forward-ref to the new Python section. 2. New 'Python / Datetime Hygiene' subsection under EXPLICITE VERBOTE. Documents: - Why utcnow() is banned (naive dt + Py 3.12 deprecation + 3.14 removal) - Why bare datetime.now() is also banned (local-tz leak) - The required pattern: datetime.now(timezone.utc) - When to keep the legacy 'Z' suffix (external wire-format / log consumers) vs when '+00:00' is fine (internal sqlite/state JSON) - Where the rule is enforced: scripts/check_banned_patterns.py - Where the tests live: UtcnowBanTests YAML-frontmatter format preserved (content: | scalar, 2-space indent, manually verified via python3 indentation-scan). No code changes. CI's check_banned_patterns.py will pass unchanged because banned tokens inside markdown frontmatter aren't scanned. Co-authored-by: v0 agent (Delqhi) <agent@v0.app>
1 parent fca332b commit b6ac8be

1 file changed

Lines changed: 29 additions & 1 deletion

File tree

survey-cli/AGENTS.md

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ content: |
3333
### Pflicht-Prozedur (IN DIESER REIHENFOLGE - KEIN VERKÜRZEN!):
3434
1. **Explore Subagent STARTEN**\: Scan ALLER Repos und Code-Dateien (rekursiv!)
3535
2. **Kategorisieren**\: DELETE (alt/broken/banned) | ️ LEGACY | ACTIVE
36-
3. **BANNED-Patterns prüfen**\: playstealth, webauto-nodriver, pkill -f Google Chrome, hardcoded PIDs, --remote-allow-origins=* ohne Quotes
36+
3. **BANNED-Patterns prüfen**\: playstealth, webauto-nodriver, pkill -f Google Chrome, hardcoded PIDs, --remote-allow-origins=* ohne Quotes, `datetime.utcnow()` (siehe Python-Sektion unten)
3737
4. **Löschen**\: Alle DELETE Dateien SOFORT entfernen (kein "vielleicht noch nützlich")
3838
5. **Kommentieren**\: Jede verbleibende Code-Datei mit EXTREMEN Kommentaren ausstatten:
3939
- **Was macht diese Datei?** (WARUM existiert sie?)
@@ -77,6 +77,34 @@ content: |
7777
- skylight-cli click --element-index - Index instabil
7878
- Hardcoded PIDs - dynamisch, niemals hardcodieren
7979
80+
### Python / Datetime Hygiene (SR-187, Issue #186)
81+
82+
**REGEL: KEIN naiver Datetime im Survey-CLI. EVER.**
83+
84+
- `datetime.utcnow()` - BANNED (Python 3.12 Deprecation, removal in 3.14)
85+
- Liefert **naive** Datetime → silent off-by-tz beim Vergleich mit tz-aware DB-Spalten
86+
- Wird vom Path-Guard automatisch geblockt: `scripts/check_banned_patterns.py`
87+
- `datetime.now()` ohne tz - BANNED aus demselben Grund (lokale Zeitzone leakt rein)
88+
- `datetime.now(timezone.utc)` - PFLICHT für alle neuen Timestamps
89+
```python
90+
from datetime import datetime, timezone
91+
ts = datetime.now(timezone.utc) # aware, UTC
92+
iso = ts.isoformat() # "2026-05-13T10:00:00+00:00"
93+
legacy_z = iso.replace("+00:00", "Z") # NUR wenn Wire-Format/Log-Konsument
94+
# historisch "Z" erwartet (z.B.
95+
# command_registry.json, jsonl-Logs)
96+
```
97+
98+
**Wo das wichtig ist (Stand SR-187 / PR #191):**
99+
- `survey-cli/commands/answer_survey.py` - command_registry.json wire-format → "Z"-Suffix erhalten
100+
- `survey-cli/survey/captcha/fallback_chain.py` - captcha-failures-YYYYMMDD.jsonl Konsumenten → "Z"-Suffix erhalten
101+
- `survey-cli/survey/daemon/answer_engine.py` - sqlite `answer_history.created_at` → "+00:00" ist OK, matched DB-Spalten
102+
- `survey-cli/survey/daemon/survey_agent_graph.py` - LangGraph state JSON intern → "+00:00" ist OK
103+
104+
**Warum die Differenzierung?** Externe Konsumenten (CI-Logs, dashboards) parsen evtl. nur `^.*Z$`. Interne sqlite/state JSONs vergleichen direkt mit tz-aware Werten, dort ist `+00:00` semantisch korrekt. Im Zweifel: "Z" emittieren via `.replace("+00:00", "Z")` ist immer rückwärtskompatibel.
105+
106+
**Enforcement:** `python3 scripts/check_banned_patterns.py` (CI + lokaler pre-commit). Tests in `scripts/tests/test_check_banned_patterns.py::UtcnowBanTests`.
107+
80108
## NEMO Architecture
81109
82110
```

0 commit comments

Comments
 (0)