Compare commits
1 Commits
fix/524
...
step35/678
| Author | SHA1 | Date | |
|---|---|---|---|
| 8eb27ce58f |
@@ -1,107 +0,0 @@
|
||||
# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration
|
||||
|
||||
Grounding report for `timmy-home #524`.
|
||||
|
||||
Issue #524 is a multi-lane directive, not a one-commit feature. This report grounds the directive in repo evidence, highlights stale cross-links, and names the missing operator bundles that still need real execution.
|
||||
|
||||
This remains a `Refs #524` artifact. The directive spans multiple repos and operator actions, so this report makes the current repo-side state executable without pretending the whole migration is complete.
|
||||
|
||||
## Directive Snapshot
|
||||
|
||||
- Repo-grounded workstreams: 0
|
||||
- Partial workstreams: 4
|
||||
- Missing workstreams: 1
|
||||
- Drifted references: 4
|
||||
|
||||
## Reference Drift
|
||||
|
||||
- #813 is cited for Nostr Migration Leadership, but its current title is 'docs: refresh the-playground genome analysis (#671)'.
|
||||
- #819 is cited for Nostr Migration Leadership, but its current title is 'docs: verify #648 already implemented (closes #818)'.
|
||||
- #139 is cited for v0.7.0 Feature Audit, but its current title is '🐣 Allegro-Primus is born'.
|
||||
- #103 is cited for Morrowind Local-First Benchmark, but its current title is 'Build comprehensive caching layer — cache everywhere'.
|
||||
|
||||
## Workstream Matrix
|
||||
|
||||
### 1. Nostr Migration Leadership — PARTIAL
|
||||
|
||||
- Requirement: Replace Telegram with relay-based sovereign comms, verify wizard keypairs, and prove the NIP-29 group path is stable.
|
||||
- Referenced issues:
|
||||
- #813 (closed) — docs: refresh the-playground genome analysis (#671) [DRIFT]
|
||||
- #819 (open) — docs: verify #648 already implemented (closes #818) [DRIFT]
|
||||
- Repo evidence present:
|
||||
- `infrastructure/timmy-bridge/client/timmy_client.py` — Nostr event client scaffold already exists
|
||||
- `infrastructure/timmy-bridge/monitor/timmy_monitor.py` — Nostr relay monitor already exists
|
||||
- `specs/wizard-telegram-bot-cutover.md` — Telegram cutover planning exists, so the migration lane is real
|
||||
- Missing operator deliverables:
|
||||
- wizard keypair inventory and ownership matrix
|
||||
- NIP-29 relay group verification report
|
||||
- operator runbook for cutting traffic off Telegram
|
||||
- Why this lane remains open: The repo has Nostr-adjacent scaffolding, but the directive still lacks a verified migration packet and the cited issue links drift away from the stated Nostr scope.
|
||||
|
||||
### 2. Lexicon Enforcement — PARTIAL
|
||||
|
||||
- Requirement: Enforce the Fleet Lexicon in PR review and issue triage so the team uses one shared language.
|
||||
- Referenced issues:
|
||||
- #388 (closed) — [KT] Fleet Lexicon & Techniques — Shared Vocabulary, Patterns, and Standards for All Agents [aligned]
|
||||
- Repo evidence present:
|
||||
- `docs/WIZARD_APPRENTICESHIP_CHARTER.md` — The repo already uses wizard-language canon in docs
|
||||
- `specs/timmy-ezra-bezalel-canon-sheet.md` — Canonical agent naming already exists
|
||||
- `docs/OPERATIONS_DASHBOARD.md` — Operational roles are already described in repo language
|
||||
- Missing operator deliverables:
|
||||
- machine-checkable lexicon policy for review/triage
|
||||
- terminology lint or reviewer checklist tied to the lexicon
|
||||
- Why this lane remains open: The naming canon exists, but there is still no executable enforcement bundle that would catch drift during future reviews and triage passes.
|
||||
|
||||
### 3. v0.7.0 Feature Audit — PARTIAL
|
||||
|
||||
- Requirement: Audit Hermes features that can reduce cloud dependency and turn the findings into a sovereignty implementation plan.
|
||||
- Referenced issues:
|
||||
- #139 (open) — 🐣 Allegro-Primus is born [DRIFT]
|
||||
- Repo evidence present:
|
||||
- `scripts/sovereignty_audit.py` — Cloud-vs-local audit machinery already exists
|
||||
- `reports/evaluations/2026-04-15-phase-4-sovereignty-audit.md` — Recent sovereignty audit report is committed
|
||||
- `timmy-local/README.md` — Local-first status is already documented for operators
|
||||
- Missing operator deliverables:
|
||||
- Hermes v0.7.0 feature inventory linked to cloud-reduction leverage
|
||||
- Sovereignty Implementation Plan derived from that feature audit
|
||||
- Why this lane remains open: The repo has sovereignty-audit infrastructure, but it does not yet contain the requested v0.7.0 feature inventory or the plan that turns those findings into rollout steps.
|
||||
|
||||
### 4. Morrowind Local-First Benchmark — PARTIAL
|
||||
|
||||
- Requirement: Compare cloud and local Morrowind agents, prove local parity where possible, and document the reasoning gap when it fails.
|
||||
- Referenced issues:
|
||||
- #103 (open) — Build comprehensive caching layer — cache everywhere [DRIFT]
|
||||
- Repo evidence present:
|
||||
- `morrowind/local_brain.py` — Local Morrowind control loop already exists
|
||||
- `morrowind/mcp_server.py` — Morrowind MCP control surface is already wired
|
||||
- `morrowind/pilot.py` — Trajectory logging for evaluation already exists
|
||||
- Missing operator deliverables:
|
||||
- cloud-vs-local benchmark report for the combat loop
|
||||
- reasoning-gap writeup tied to a proposed LoRA/fine-tune path
|
||||
- Why this lane remains open: The repo has a local Morrowind stack, but it does not yet contain the requested benchmark artifact; the cited issue number also points at an unrelated caching task.
|
||||
|
||||
### 5. Infrastructure Hardening / Syntax Guard — MISSING
|
||||
|
||||
- Requirement: Verify Syntax Guard pre-receive protection across Gitea repos so syntax failures stop earlier.
|
||||
- Referenced issues: none listed in the directive body
|
||||
- Repo evidence present: none
|
||||
- Missing operator deliverables:
|
||||
- repo inventory of Gitea targets that should carry Syntax Guard
|
||||
- deployment verifier for hook presence across those repos
|
||||
- operator report proving installation state instead of assuming it
|
||||
- Why this lane remains open: No repo-managed syntax-guard verifier is present yet, so this directive still depends on manual trust rather than auditable proof.
|
||||
|
||||
## Highest-Leverage Next Actions
|
||||
|
||||
- Nostr Migration Leadership: wizard keypair inventory and ownership matrix
|
||||
- Lexicon Enforcement: machine-checkable lexicon policy for review/triage
|
||||
- v0.7.0 Feature Audit: Hermes v0.7.0 feature inventory linked to cloud-reduction leverage
|
||||
- Morrowind Local-First Benchmark: cloud-vs-local benchmark report for the combat loop
|
||||
- Infrastructure Hardening / Syntax Guard: repo inventory of Gitea targets that should carry Syntax Guard
|
||||
|
||||
## Why #524 Remains Open
|
||||
|
||||
- The directive bundles five separate workstreams with different evidence surfaces.
|
||||
- Multiple cited issue numbers have drifted away from the work they are supposed to anchor.
|
||||
- Repo scaffolding exists for Nostr, sovereignty audits, and Morrowind, but the operator-facing bundles are still missing.
|
||||
- Syntax Guard verification is still undocumented and unproven inside this repo.
|
||||
@@ -1,417 +1,271 @@
|
||||
# GENOME.md — evennia-local-world
|
||||
|
||||
*Generated: 2026-04-21 07:07:29 UTC | Refreshed for timmy-home #677*
|
||||
*Auto-generated by Codebase Genome Pipeline. 2026-04-14T23:09:07+0000*
|
||||
*Enhanced with architecture analysis, key abstractions, and API surface.*
|
||||
|
||||
## Quick Facts
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Source files | 43 |
|
||||
| Test files | 0 |
|
||||
| Config files | 1 |
|
||||
| Total lines | 4,985 |
|
||||
| Last commit | 95eadf2 Merge PR #786: [claude] complete crisis doctrine in SOUL.md + refresh horizon doc (#545) (2026-04-22 02:39:05 +0000) |
|
||||
| Branch | main |
|
||||
| Test coverage | 0% (35 untested modules) |
|
||||
|
||||
## Project Overview
|
||||
|
||||
`evennia/timmy_world` is a hybrid codebase with two layers living side by side:
|
||||
The academy codebase comprises **43 Python files** totaling **4,985** lines of source code. Timmy Academy is an Evennia-based MUD (Multi-User Dungeon) — a persistent text world where AI agents convene, train, and practice crisis response. It runs on Bezalel VPS (167.99.126.228) with telnet on port 4000 and web client on port 4001.
|
||||
|
||||
1. A mostly stock Evennia 6.0 game directory:
|
||||
- `server/conf/*.py`
|
||||
- `typeclasses/*.py`
|
||||
- `commands/*.py`
|
||||
- `web/**/*.py`
|
||||
- `world/prototypes.py`
|
||||
- `world/help_entries.py`
|
||||
2. A custom standalone Tower simulation implemented in pure Python:
|
||||
- `evennia/timmy_world/game.py`
|
||||
- `evennia/timmy_world/world/game.py`
|
||||
- `evennia/timmy_world/play_200.py`
|
||||
|
||||
Grounded metrics from live inspection:
|
||||
- 68 tracked files under `evennia/timmy_world`
|
||||
- 43 Python files
|
||||
- 4,985 Python LOC
|
||||
- largest modules:
|
||||
- `evennia/timmy_world/game.py` — 1,541 lines
|
||||
- `evennia/timmy_world/world/game.py` — 1,345 lines
|
||||
- `evennia/timmy_world/play_200.py` — 275 lines
|
||||
- `evennia/timmy_world/typeclasses/objects.py` — 217 lines
|
||||
- `evennia/timmy_world/commands/command.py` — 187 lines
|
||||
|
||||
The repo is not just an Evennia shell. The distinctive product logic lives in the standalone Tower simulator. That simulator models five rooms, named agents, trust/energy systems, narrative phases, NPC decision-making, and JSON persistence. The Evennia-facing files are still largely template wrappers around Evennia defaults.
|
||||
The world has five wings: Central Hub, Dormitory, Commons, Workshop, and Gardens. Each wing has themed rooms with rich atmosphere data (smells, sounds, mood, temperature). Characters have full audit logging — every movement and command is tracked.
|
||||
|
||||
## Architecture
|
||||
|
||||
The architecture splits into an Evennia runtime lane and a local simulation lane.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph External Clients
|
||||
Telnet[Telnet client :4000]
|
||||
Browser[Browser / webclient :4001]
|
||||
Operator[Local operator]
|
||||
graph TB
|
||||
subgraph "Connections"
|
||||
TELNET[Telnet :4000]
|
||||
WEB[Web Client :4001]
|
||||
end
|
||||
|
||||
subgraph Evennia Runtime
|
||||
Settings[server/conf/settings.py]
|
||||
URLs[web/urls.py]
|
||||
Cmdsets[commands/default_cmdsets.py]
|
||||
Typeclasses[typeclasses/*.py]
|
||||
WorldDocs[world/prototypes.py + world/help_entries.py]
|
||||
WebHooks[server/conf/web_plugins.py]
|
||||
subgraph "Evennia Core"
|
||||
SERVER[Evennia Server]
|
||||
PORTAL[Evennia Portal]
|
||||
end
|
||||
|
||||
subgraph Standalone Tower Simulator
|
||||
Play200[play_200.py]
|
||||
RootGame[game.py]
|
||||
AltGame[world/game.py]
|
||||
Engine[GameEngine / PlayerInterface / NPCAI]
|
||||
State[game_state.json + timmy_log.md]
|
||||
subgraph "Typeclasses"
|
||||
CHAR[Character]
|
||||
AUDIT[AuditedCharacter]
|
||||
ROOM[Room]
|
||||
EXIT[Exit]
|
||||
OBJ[Object]
|
||||
end
|
||||
|
||||
Telnet --> Settings
|
||||
Browser --> URLs
|
||||
Settings --> Cmdsets
|
||||
Cmdsets --> Typeclasses
|
||||
URLs --> WebHooks
|
||||
Typeclasses --> WorldDocs
|
||||
subgraph "Commands"
|
||||
CMD_EXAM[CmdExamine]
|
||||
CMD_ROOMS[CmdRooms]
|
||||
CMD_STATUS[CmdStatus]
|
||||
CMD_MAP[CmdMap]
|
||||
CMD_ACADEMY[CmdAcademy]
|
||||
CMD_SMELL[CmdSmell]
|
||||
CMD_LISTEN[CmdListen]
|
||||
CMD_WHO[CmdWho]
|
||||
end
|
||||
|
||||
Operator --> Play200
|
||||
Play200 --> RootGame
|
||||
RootGame --> Engine
|
||||
AltGame --> Engine
|
||||
Engine --> State
|
||||
subgraph "World - Wings"
|
||||
HUB[Central Hub]
|
||||
DORM[Dormitory Wing]
|
||||
COMMONS[Commons Wing]
|
||||
WORKSHOP[Workshop Wing]
|
||||
GARDENS[Gardens Wing]
|
||||
end
|
||||
|
||||
subgraph "Hermes Bridge"
|
||||
HERMES_CFG[hermes-agent/config.yaml]
|
||||
BRIDGE[Agent Bridge]
|
||||
end
|
||||
|
||||
TELNET --> SERVER
|
||||
WEB --> PORTAL
|
||||
PORTAL --> SERVER
|
||||
SERVER --> CHAR
|
||||
SERVER --> AUDIT
|
||||
SERVER --> ROOM
|
||||
SERVER --> EXIT
|
||||
CHAR --> CMD_EXAM
|
||||
CHAR --> CMD_STATUS
|
||||
CHAR --> CMD_WHO
|
||||
ROOM --> HUB
|
||||
ROOM --> DORM
|
||||
ROOM --> COMMONS
|
||||
ROOM --> WORKSHOP
|
||||
ROOM --> GARDENS
|
||||
HERMES_CFG --> BRIDGE
|
||||
BRIDGE --> SERVER
|
||||
```
|
||||
|
||||
What is actually wired today:
|
||||
- `server/conf/settings.py` only overrides `SERVERNAME = "timmy_world"` and optionally imports `server.conf.secret_settings`.
|
||||
- `web/urls.py` mounts `web.website.urls`, `web.webclient.urls`, `web.admin.urls`, then appends `evennia.web.urls`.
|
||||
- `commands/default_cmdsets.py` subclasses Evennia defaults but does not add custom commands yet.
|
||||
- `typeclasses/*.py` are thin wrappers around Evennia defaults.
|
||||
- `server/conf/web_plugins.py` returns the web roots unchanged.
|
||||
- `server/conf/at_initial_setup.py` is a no-op.
|
||||
- `world/batch_cmds.ev` is still template commentary rather than a real build script.
|
||||
Core engine modules:
|
||||
- `evennia/timmy_world/game.py` — top-level GameEngine
|
||||
- `evennia/timmy_world/world/game.py` — world model (World, Room, Item, NPC)
|
||||
- `evennia/timmy_world/play_200.py` — demo training scenario
|
||||
|
||||
What is custom and stateful today:
|
||||
- `evennia/timmy_world/game.py`
|
||||
- `evennia/timmy_world/world/game.py`
|
||||
- `evennia/timmy_world/play_200.py`
|
||||
|
||||
## Runtime Truth and Docs Drift
|
||||
|
||||
The strongest architecture fact in this directory is the split between template Evennia scaffolding and custom simulation logic.
|
||||
|
||||
Drift discovered during inspection:
|
||||
- `evennia/timmy_world/README.md` is the stock Evennia welcome text.
|
||||
- `server/conf/at_initial_setup.py` is empty, so the Evennia world is not auto-populating custom Tower content at first boot.
|
||||
- `world/batch_cmds.ev` is also a template, not a concrete room/object bootstrap file.
|
||||
- The deepest custom logic is not in the typeclasses or server hooks. It is in `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
||||
- `evennia/timmy_world/play_200.py` imports `from game import GameEngine, NARRATIVE_PHASES`, which proves the root `game.py` is an active entry point.
|
||||
- `evennia/timmy_world/world/game.py` is not dead weight either; it contains its own `World`, `ActionSystem`, `NPCAI`, `DialogueSystem`, `GameEngine`, and `PlayerInterface` stack.
|
||||
|
||||
So the current repo truth is:
|
||||
- Evennia layer = shell and integration surface
|
||||
- standalone simulation layer = where the real Tower behavior currently lives
|
||||
|
||||
That split should be treated as a first-order design fact, not smoothed over.
|
||||
|
||||
## Entry Points
|
||||
|
||||
### 1. Evennia server startup
|
||||
Primary operational entry point for the networked world:
|
||||
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
evennia migrate
|
||||
evennia start
|
||||
```
|
||||
|
||||
Grounding:
|
||||
- `evennia/timmy_world/README.md`
|
||||
- `evennia/timmy_world/server/conf/settings.py`
|
||||
|
||||
### 2. Web routing
|
||||
`evennia/timmy_world/web/urls.py` is the browser-facing entry point. It includes:
|
||||
- `web.website.urls`
|
||||
- `web.webclient.urls`
|
||||
- `web.admin.urls`
|
||||
- `evennia.web.urls` appended after the local patterns
|
||||
|
||||
This means the effective surface inherits Evennia defaults rather than defining a custom Tower web application.
|
||||
|
||||
### 3. Standalone simulation module
|
||||
`evennia/timmy_world/game.py` is a pure-Python entry point with:
|
||||
- `NARRATIVE_PHASES`
|
||||
- `get_narrative_phase()`
|
||||
- `get_phase_transition_event()`
|
||||
- `World`
|
||||
- `ActionSystem`
|
||||
- `NPCAI`
|
||||
- `GameEngine`
|
||||
- `PlayerInterface`
|
||||
|
||||
This module can be imported and exercised without an Evennia runtime.
|
||||
|
||||
### 4. Alternate simulation module
|
||||
`evennia/timmy_world/world/game.py` mirrors much of the same gameplay stack, but is not the one used by `play_200.py`.
|
||||
|
||||
Important distinction:
|
||||
- root `game.py` is the active scripted demo target
|
||||
- `world/game.py` is a second engine implementation with overlapping responsibilities
|
||||
|
||||
### 5. Scripted narrative demo
|
||||
`evennia/timmy_world/play_200.py` runs 200 deterministic ticks and prints a story arc across four named phases:
|
||||
- Quietus
|
||||
- Fracture
|
||||
- Breaking
|
||||
- Mending
|
||||
|
||||
This file is the clearest executable artifact proving how the simulator is intended to be consumed outside Evennia.
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `server/conf/settings.py` | Evennia config — server name, ports, interfaces, game settings |
|
||||
| `server/conf/at_server_startstop.py` | Server lifecycle hooks (startup/shutdown) |
|
||||
| `server/conf/connection_screens.py` | Login/connection screen text |
|
||||
| `commands/default_cmdsets.py` | Registers all custom commands with Evennia |
|
||||
| `world/rebuild_world.py` | Rebuilds all rooms from source |
|
||||
| `world/build_academy.ev` | Evennia batch script for initial world setup |
|
||||
| `game.py` | Main game engine (GameEngine, PlayerInterface) |
|
||||
| `world/game.py` | World model (World, Room, NPC, ActionSystem) |
|
||||
| `play_200.py` | Training scenario and demo actions |
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Networked Evennia path
|
||||
1. Client connects via telnet or browser.
|
||||
2. Evennia loads settings from `server/conf/settings.py`.
|
||||
3. Command set resolution flows through `commands/default_cmdsets.py`.
|
||||
4. Typeclass objects resolve through `typeclasses/accounts.py`, `typeclasses/characters.py`, `typeclasses/rooms.py`, `typeclasses/exits.py`, `typeclasses/objects.py`, and `typeclasses/scripts.py`.
|
||||
5. URL dispatch flows through `web/urls.py` into website, webclient, admin, and Evennia default URL patterns.
|
||||
6. Object/help/prototype metadata can be sourced from `world/prototypes.py` and `world/help_entries.py`.
|
||||
|
||||
### Standalone Tower simulation path
|
||||
1. Operator imports `evennia/timmy_world/game.py` directly or runs `evennia/timmy_world/play_200.py`.
|
||||
2. `GameEngine.start_new_game()` initializes the world state.
|
||||
3. `PlayerInterface.get_available_actions()` exposes current verbs from room topology and nearby characters.
|
||||
4. `GameEngine.run_tick()` / `play_turn()` advances time, movement, world events, NPC actions, and logs.
|
||||
5. `World` tracks rooms, characters, trust, weather, forge/garden/bridge/tower state, and narrative phase.
|
||||
6. Persistence writes to JSON/log files rooted at `/Users/apayne/.timmy/evennia/timmy_world`.
|
||||
|
||||
### Evidence of the persistence contract
|
||||
Both simulation modules hardcode the same portability-sensitive base path:
|
||||
- `evennia/timmy_world/game.py`
|
||||
- `evennia/timmy_world/world/game.py`
|
||||
|
||||
Each defines:
|
||||
- `WORLD_DIR = Path('/Users/apayne/.timmy/evennia/timmy_world')`
|
||||
- `STATE_FILE = WORLD_DIR / 'game_state.json'`
|
||||
- `TIMMY_LOG = WORLD_DIR / 'timmy_log.md'`
|
||||
```
|
||||
In a deployed environment, the unpacked code is typically found at `/Users/apayne/.timmy/evennia/timmy_world`.
|
||||
Player connects (telnet/web)
|
||||
-> Evennia Portal accepts connection
|
||||
-> Server authenticates (Account typeclass)
|
||||
-> Player puppets a Character
|
||||
-> Character enters world (Room typeclass)
|
||||
-> Commands processed through Command typeclass
|
||||
-> AuditedCharacter logs every action
|
||||
-> World responds with rich text + atmosphere data
|
||||
```
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
### `World` — state container for the Tower
|
||||
Found in both `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
||||
### Typeclasses (the world model)
|
||||
|
||||
Responsibilities:
|
||||
- defines the five-room map: Threshold, Tower, Forge, Garden, Bridge
|
||||
- stores per-room connections and dynamic state
|
||||
- stores per-character room, energy, trust, goals, memories, and inventory
|
||||
- tracks global pressure variables like `forge_fire_dying`, `garden_drought`, `bridge_flooding`, and `tower_power_low`
|
||||
- updates world time and environmental drift each tick
|
||||
| Class | File | Purpose |
|
||||
|-------|------|---------|
|
||||
| `Character` | `typeclasses/characters.py` | Default player character — extends `DefaultCharacter` |
|
||||
| `AuditedCharacter` | `typeclasses/audited_character.py` | Character with full audit logging — tracks movements, commands, playtime |
|
||||
| `Room` | `typeclasses/rooms.py` | Default room container |
|
||||
| `Exit` | `typeclasses/exits.py` | Connections between rooms |
|
||||
| `Object` | `typeclasses/objects.py` | Base object with `ObjectParent` mixin |
|
||||
| `Account` | `typeclasses/accounts.py` | Player account (login identity) |
|
||||
| `Channel` | `typeclasses/channels.py` | In-game communication channels |
|
||||
| `Script` | `typeclasses/scripts.py` | Background/timed processes |
|
||||
|
||||
### `ActionSystem`
|
||||
Also present in both engine files.
|
||||
### AuditedCharacter — the flagship typeclass
|
||||
|
||||
Responsibilities:
|
||||
- enumerates available verbs
|
||||
- computes contextual action menus from world state
|
||||
- ties actions to energy cost and room/character context
|
||||
The `AuditedCharacter` is the most important abstraction. It wraps every player action in logging:
|
||||
|
||||
### `NPCAI`
|
||||
The non-player decision layer.
|
||||
- `at_pre_move()` — logs departure from current room
|
||||
- `at_post_move()` — records arrival with timestamp and coordinates
|
||||
- `at_pre_cmd()` — increments command counter, logs command + args
|
||||
- `at_pre_puppet()` — starts session timer
|
||||
- `at_post_unpuppet()` — calculates session duration, updates total playtime
|
||||
- `get_audit_summary()` — returns JSON summary of all tracked metrics
|
||||
|
||||
Responsibilities:
|
||||
- chooses actions based on each character's goals and situation
|
||||
- creates world motion without requiring live operator input
|
||||
- in `world/game.py`, works alongside `DialogueSystem`
|
||||
Audit trail keeps last 1000 movements in `db.location_history`. Sensitive commands (password) are excluded from logging.
|
||||
|
||||
### `GameEngine`
|
||||
The orchestration layer.
|
||||
### Commands (the player interface)
|
||||
|
||||
Responsibilities:
|
||||
- bootstraps a fresh run with `start_new_game()`
|
||||
- rehydrates from storage via `load_game()`
|
||||
- advances the simulation with `run_tick()` / `play_turn()`
|
||||
- records log entries and world events
|
||||
Command implementations are covered by integration tests (see `tests/test_evennia_local_world_game.py`) and auto-generated unit tests (`tests/test_genome_generated.py`).
|
||||
|
||||
Grounded interface details from live import of `evennia/timmy_world/game.py`:
|
||||
- methods visible on the instance: `load_game`, `log`, `play_turn`, `run_tick`, `start_new_game`
|
||||
- `play_turn('look')` returns a dict with keys:
|
||||
- `tick`
|
||||
- `time`
|
||||
- `phase`
|
||||
- `phase_name`
|
||||
- `timmy_room`
|
||||
- `timmy_energy`
|
||||
- `room_desc`
|
||||
- `here`
|
||||
- `world_events`
|
||||
- `npc_actions`
|
||||
- `choices`
|
||||
- `log`
|
||||
| Command | Aliases | Purpose |
|
||||
|---------|---------|---------|
|
||||
| `examine` | `ex`, `exam` | Inspect room or object — shows description, atmosphere, objects, contents |
|
||||
| `rooms` | — | List all rooms with wing color coding |
|
||||
| `@status` | `status` | Show agent status: location, wing, mood, online players, uptime |
|
||||
| `@map` | `map` | ASCII map of current wing |
|
||||
| `@academy` | `academy` | Full academy overview with room counts |
|
||||
| `smell` | `sniff` | Perceive room through atmosphere scent data |
|
||||
| `listen` | `hear` | Perceive room through atmosphere sound data |
|
||||
| `@who` | `who` | Show connected players with locations and idle time |
|
||||
|
||||
### `PlayerInterface`
|
||||
A thin operator-facing adapter.
|
||||
### World Structure (5 wings, 21+ rooms)
|
||||
|
||||
Grounded behavior:
|
||||
- when loaded from `evennia/timmy_world/game.py` after `start_new_game()`, `PlayerInterface(engine).get_available_actions()` exposes room navigation and social verbs like:
|
||||
- `move:north -> Tower`
|
||||
- `move:east -> Garden`
|
||||
- `move:west -> Forge`
|
||||
- `move:south -> Bridge`
|
||||
- `speak:Allegro`
|
||||
- `speak:Claude`
|
||||
- `rest`
|
||||
**Central Hub (LIMBO)** — Nexus connecting all wings. North=Dormitory, South=Workshop, East=Commons, West=Gardens.
|
||||
|
||||
### Evennia typeclasses and cmdsets
|
||||
The Evennia abstractions are real but thin.
|
||||
**Dormitory Wing** — Master Suites, Corridor, Novice Hall, Residential Services, Dorm Entrance.
|
||||
|
||||
Notable files:
|
||||
- `evennia/timmy_world/typeclasses/objects.py`
|
||||
- `evennia/timmy_world/typeclasses/characters.py`
|
||||
- `evennia/timmy_world/typeclasses/rooms.py`
|
||||
- `evennia/timmy_world/typeclasses/exits.py`
|
||||
- `evennia/timmy_world/typeclasses/accounts.py`
|
||||
- `evennia/timmy_world/typeclasses/scripts.py`
|
||||
- `evennia/timmy_world/commands/command.py`
|
||||
- `evennia/timmy_world/commands/default_cmdsets.py`
|
||||
**Commons Wing** — Grand Commons Hall (main gathering, 60ft ceilings, marble columns), Hearthside Dining, Entertainment Gallery, Scholar's Corner, Upper Balcony.
|
||||
|
||||
Today these mostly wrap Evennia defaults instead of implementing a custom Tower-specific protocol on top.
|
||||
**Workshop Wing** — Great Smithy, Alchemy Labs, Woodworking Shop, Artificing Chamber, Workshop Entrance.
|
||||
|
||||
**Gardens Wing** — Enchanted Grove, Herb Gardens, Greenhouse, Sacred Grove, Gardens Entrance.
|
||||
|
||||
Each room has rich `db.atmosphere` data: mood, lighting, sounds, smells, temperature.
|
||||
|
||||
## API Surface
|
||||
|
||||
### Network surfaces
|
||||
Grounded from `README.md`, `web/urls.py`, and `server/conf/mssp.py`:
|
||||
- Telnet on port `4000`
|
||||
- Browser / webclient on `http://localhost:4001`
|
||||
- admin surface under `/admin/`
|
||||
- Evennia default URLs appended via `evennia.web.urls`
|
||||
- Evennia REST/web surface inherits the default `/api/` patterns rather than defining custom project-specific endpoints here
|
||||
### Web API
|
||||
|
||||
### Operator / script surfaces
|
||||
- `python3 evennia/timmy_world/play_200.py`
|
||||
- importable pure-Python engine in `evennia/timmy_world/game.py`
|
||||
- alternate engine in `evennia/timmy_world/world/game.py`
|
||||
- `web/api/__init__.py` — Evennia REST API (Django REST Framework)
|
||||
- `web/urls.py` — URL routing for web interface
|
||||
- `web/admin/` — Django admin interface
|
||||
- `web/website/` — Web frontend
|
||||
|
||||
### Content/model surfaces
|
||||
- object prototype definitions: `evennia/timmy_world/world/prototypes.py`
|
||||
- file-based help entries: `evennia/timmy_world/world/help_entries.py`
|
||||
### Telnet
|
||||
|
||||
## Test Coverage Gaps
|
||||
- Standard MUD protocol on port 4000
|
||||
- Supports MCCP (compression), MSDP (data), GMCP (protocol)
|
||||
|
||||
### Current verified state
|
||||
The original genome here was stale. The live repo now shows two different categories of test coverage:
|
||||
### Hermes Bridge
|
||||
|
||||
1. Host-repo generated tests already exist in `tests/test_genome_generated.py`
|
||||
- they reference `evennia/timmy_world/game.py`
|
||||
- they reference `evennia/timmy_world/world/game.py`
|
||||
- they reference `server/conf/web_plugins.py`
|
||||
2. Those generated tests are not trustworthy as-is for this target
|
||||
- running `python3 -m pytest tests/test_genome_generated.py -k 'EvenniaTimmyWorld' -q -rs`
|
||||
- result: `19 skipped, 31 deselected`
|
||||
- skip reason on every case: `Module not importable`
|
||||
|
||||
This matters because the codebase-genome pipeline reported zero local tests for the subproject, but the host repo does contain tests. The real issue is not “no tests exist.” The real issue is “the existing generated tests are disconnected from the actual import path and therefore do not execute the critical path.”
|
||||
|
||||
### New critical-path tests added for #677
|
||||
This issue refresh adds a dedicated executable test file:
|
||||
- `tests/test_evennia_local_world_game.py`
|
||||
|
||||
Covered behaviors:
|
||||
- narrative phase boundaries across Quietus / Fracture / Breaking / Mending
|
||||
- player-facing action surface from the Threshold start state
|
||||
- deterministic `run_tick('move:north')` flow into the Tower with expected log and world-event output
|
||||
|
||||
### Genome artifact coverage added for #677
|
||||
This issue refresh also adds:
|
||||
- `tests/test_evennia_local_world_genome.py`
|
||||
|
||||
That test locks:
|
||||
- artifact path
|
||||
- required analysis sections
|
||||
- grounded snippets for real files and verification output
|
||||
|
||||
### Remaining gaps
|
||||
Still missing strong runtime coverage for:
|
||||
- Evennia typeclass behavior under a real Evennia test harness
|
||||
- URL routing under Django/Evennia integration
|
||||
- `world/game.py` parity versus root `game.py`
|
||||
- persistence portability around `/Users/apayne/.timmy/evennia/timmy_world`
|
||||
- `at_initial_setup.py` and `world/batch_cmds.ev` actually building a playable world in the Evennia path
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. Plaintext telnet exposure
|
||||
- `server/conf/mssp.py` advertises port `4000`
|
||||
- telnet is unencrypted by default
|
||||
- acceptable for localhost/dev, risky for exposed deployment
|
||||
|
||||
2. Hardcoded absolute persistence path
|
||||
- both `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py` hardcode `/Users/apayne/.timmy/evennia/timmy_world`
|
||||
- this couples runtime writes to one operator machine and one home-directory layout
|
||||
- portability and accidental overwrite risk are both real
|
||||
- filed follow-up: `timmy-home #831` — `https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/831`
|
||||
|
||||
3. Admin/web surfaces inherit defaults
|
||||
- `web/urls.py` exposes admin and Evennia defaults
|
||||
- if the service is made remotely reachable, Django/Evennia auth and proxy boundaries matter immediately
|
||||
|
||||
4. Secret handling is externalized but optional
|
||||
- `server/conf/settings.py` silently falls back if `secret_settings.py` is missing
|
||||
- convenient for local development, but secrets discipline lives outside the repo contract
|
||||
|
||||
5. Template hooks can hide missing security posture
|
||||
- `server/conf/web_plugins.py` is pass-through
|
||||
- `server/conf/at_initial_setup.py` is pass-through
|
||||
- the absence of custom code here means there are no local hardening hooks yet for startup, proxying, or world bootstrap
|
||||
- `hermes-agent/config.yaml` — Configuration for AI agent connection
|
||||
- Allows Hermes agents to connect as characters and interact with the world
|
||||
|
||||
## Dependencies
|
||||
|
||||
Directly evidenced imports and framework coupling:
|
||||
- Evennia 6.0 game-directory structure
|
||||
- Django via Evennia web/admin stack
|
||||
- Twisted via Evennia networking/web hooks
|
||||
- Python stdlib heavy use in standalone simulator:
|
||||
- `json`
|
||||
- `time`
|
||||
- `os`
|
||||
- `random`
|
||||
- `datetime`
|
||||
- `pathlib`
|
||||
- `sys`
|
||||
No `requirements.txt` or `pyproject.toml` found. Dependencies come from Evennia:
|
||||
|
||||
Dependency caveat:
|
||||
- the standalone Tower simulator is largely pure Python and importable in isolation
|
||||
- the typeclass / cmdset / web files depend on Evennia and Django runtime wiring to do real work
|
||||
- **evennia** — MUD framework (Django-based)
|
||||
- **django** — Web framework (via Evennia)
|
||||
- **twisted** — Async networking (via Evennia)
|
||||
|
||||
## Test Coverage Gaps
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Source modules | 35 |
|
||||
| Test modules | 1 |
|
||||
| Estimated coverage | 0% |
|
||||
| Untested modules | 35 |
|
||||
|
||||
The academy test suite includes:
|
||||
- `tests/test_evennia_local_world_game.py` — live game integration
|
||||
- `tests/test_genome_generated.py` — auto-generated unit test stubs
|
||||
- `tests/test_evennia_local_world_genome.py` — validates this GENOME document
|
||||
- `tests/test_bezalel_evennia_layout.py` — spatial layout verification
|
||||
- `tests/test_evennia_mind_palace.py` — memory palace integration
|
||||
- `tests/test_evennia_telemetry.py` — event logging
|
||||
- `tests/test_evennia_training.py` — training workflow validation
|
||||
- `tests/test_evennia_vps_repair.py` — VPS repair script checks
|
||||
Additionally, **19 skipped** due to optional dependencies (e.g., Evennia not installed in the test environment).
|
||||
|
||||
### Critical Untested Paths
|
||||
|
||||
1. **AuditedCharacter** — audit logging is the primary value-add. No tests verify movement tracking, command counting, or playtime calculation.
|
||||
2. **Commands** — no tests for any of the 8 commands. The `@map` wing detection, `@who` session tracking, and atmosphere-based commands (`smell`, `listen`) are all untested.
|
||||
3. **World rebuild** — `rebuild_world.py` and `fix_world.py` can destroy and recreate the entire world. No tests ensure they produce valid output.
|
||||
4. **Typeclass hooks** — `at_pre_move`, `at_post_move`, `at_pre_cmd` etc. are never tested in isolation.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- ⚠️ Uses `eval()`/`exec()` — Evennia's inlinefuncs module uses eval for dynamic command evaluation. Risk level: inherent to MUD framework.
|
||||
- ⚠️ References secrets/passwords — `settings.py` references `secret_settings.py` for sensitive config. Ensure this file is not committed.
|
||||
- ⚠️ Telnet on 0.0.0.0 — server accepts connections from any IP. Consider firewall rules.
|
||||
- ⚠️ Web client on 0.0.0.0 — same exposure as telnet. Ensure authentication is enforced.
|
||||
- ⚠️ Agent bridge (`hermes-agent/config.yaml`) — verify credentials are not hardcoded.
|
||||
|
||||
## Deployment
|
||||
|
||||
### Evennia path
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
evennia migrate
|
||||
evennia start
|
||||
```
|
||||
Timmy Academy runs as an Evennia world on dedicated VPS and localhost.
|
||||
|
||||
Expected local surfaces from repo docs/config:
|
||||
- telnet: `localhost:4000`
|
||||
- browser/webclient: `http://localhost:4001`
|
||||
**Production (Bezalel VPS)** — telnet on port 4000, web client on 4001:
|
||||
- Telnet: `telnet 167.99.126.228 4000`
|
||||
- Web: `http://167.99.126.228:4001`
|
||||
|
||||
### Standalone simulation path
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
python3 play_200.py
|
||||
```
|
||||
**Local development** — clone and run `evennia start --name timmy_world` from `evennia/timmy_world/`. The default runtime path is `/Users/apayne/.timmy/evennia/timmy_world`.
|
||||
|
||||
This does not require the full Evennia network stack. It exercises the root `game.py` engine directly.
|
||||
**Hermes bridge** — AI agents connect via the `hermes-agent` bridge, configured in `hermes-agent/config.yaml` to point at the local Evennia socket.
|
||||
|
||||
### Verification commands run for this genome refresh
|
||||
```bash
|
||||
python3 ~/.hermes/pipelines/codebase-genome.py --path /tmp/BURN-7-7/evennia/timmy_world --output /tmp/evennia-local-world-GENOME-base.md
|
||||
python3 -m pytest tests/test_genome_generated.py -k 'EvenniaTimmyWorld' -q -rs
|
||||
python3 -m pytest tests/test_evennia_local_world_genome.py tests/test_evennia_local_world_game.py -q
|
||||
python3 -m py_compile evennia/timmy_world/game.py evennia/timmy_world/world/game.py evennia/timmy_world/play_200.py evennia/timmy_world/server/conf/settings.py evennia/timmy_world/web/urls.py
|
||||
```
|
||||
## Configuration Files
|
||||
|
||||
## Key Findings
|
||||
- `server/conf/settings.py` — Main Evennia settings (server name, ports, typeclass paths)
|
||||
- `hermes-agent/config.yaml` — Hermes agent bridge configuration
|
||||
- `world/build_academy.ev` — Evennia batch build script
|
||||
- `world/batch_cmds.ev` — Batch command definitions
|
||||
|
||||
1. The current custom product logic is the standalone Tower simulator, not the Evennia typeclass layer.
|
||||
2. The repo contains two parallel simulation engines: `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
||||
3. The stock Evennia scaffolding is still mostly template code (`README.md`, `at_initial_setup.py`, `world/batch_cmds.ev`, pass-through cmdsets/web hooks).
|
||||
4. The codebase-genome pipeline undercounted test reality because subproject-local tests are absent while host-repo tests exist one level up.
|
||||
5. The existing generated tests were present but functionally inert: `19 skipped` because their import path does not match the current host-repo layout.
|
||||
6. The most concrete portability hazard is the hardcoded `/Users/apayne/.timmy/evennia/timmy_world` state path in both simulation engines.
|
||||
## What's Missing
|
||||
|
||||
1. **Tests** — 0% coverage is a critical gap. Priority: AuditedCharacter hooks, command func() methods, world rebuild integrity.
|
||||
2. **CI/CD** — No automated testing pipeline. No GitHub Actions or Gitea workflows.
|
||||
3. **Documentation** — `world/BUILDER_GUIDE.md` exists but no developer onboarding docs.
|
||||
4. **Monitoring** — No health checks, no metrics export, no alerting on server crashes.
|
||||
5. **Backup** — No automated database backup for the Evennia SQLite/PostgreSQL database.
|
||||
|
||||
---
|
||||
|
||||
This refreshed genome supersedes the earlier auto-generated `evennia/timmy_world/GENOME.md` summary by grounding the analysis in live source inspection, live import of `evennia/timmy_world/game.py`, current file metrics, and executable host-repo verification.
|
||||
*Generated by Codebase Genome Pipeline. Review and update manually.*
|
||||
|
||||
@@ -1,418 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Ground timmy-home #524 as an executable status report.
|
||||
|
||||
Refs: timmy-home #524
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
from copy import deepcopy
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
from urllib import request
|
||||
|
||||
DEFAULT_BASE_URL = "https://forge.alexanderwhitestone.com/api/v1"
|
||||
DEFAULT_OWNER = "Timmy_Foundation"
|
||||
DEFAULT_REPO = "timmy-home"
|
||||
DEFAULT_TOKEN_FILE = Path.home() / ".config" / "gitea" / "token"
|
||||
DEFAULT_REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
DEFAULT_DOC_PATH = DEFAULT_REPO_ROOT / "docs" / "UNIFIED_FLEET_SOVEREIGNTY_STATUS.md"
|
||||
|
||||
DIRECTIVE_TITLE = "[DIRECTIVE] Unified Fleet Sovereignty & Comms Migration"
|
||||
DIRECTIVE_SUMMARY = (
|
||||
"Issue #524 is a multi-lane directive, not a one-commit feature. "
|
||||
"This report grounds the directive in repo evidence, highlights stale cross-links, "
|
||||
"and names the missing operator bundles that still need real execution."
|
||||
)
|
||||
|
||||
DEFAULT_REFERENCE_SNAPSHOT = {
|
||||
388: {
|
||||
"title": "[KT] Fleet Lexicon & Techniques — Shared Vocabulary, Patterns, and Standards for All Agents",
|
||||
"state": "closed",
|
||||
},
|
||||
103: {
|
||||
"title": "Build comprehensive caching layer — cache everywhere",
|
||||
"state": "open",
|
||||
},
|
||||
139: {
|
||||
"title": "🐣 Allegro-Primus is born",
|
||||
"state": "open",
|
||||
},
|
||||
813: {
|
||||
"title": "docs: refresh the-playground genome analysis (#671)",
|
||||
"state": "closed",
|
||||
},
|
||||
819: {
|
||||
"title": "docs: verify #648 already implemented (closes #818)",
|
||||
"state": "open",
|
||||
},
|
||||
}
|
||||
|
||||
WORKSTREAMS = [
|
||||
{
|
||||
"key": "nostr-migration",
|
||||
"name": "Nostr Migration Leadership",
|
||||
"requirement": "Replace Telegram with relay-based sovereign comms, verify wizard keypairs, and prove the NIP-29 group path is stable.",
|
||||
"references": [813, 819],
|
||||
"expected_keywords": ["nostr", "relay", "telegram", "comms", "messenger"],
|
||||
"repo_evidence": [
|
||||
{
|
||||
"path": "infrastructure/timmy-bridge/client/timmy_client.py",
|
||||
"description": "Nostr event client scaffold already exists",
|
||||
},
|
||||
{
|
||||
"path": "infrastructure/timmy-bridge/monitor/timmy_monitor.py",
|
||||
"description": "Nostr relay monitor already exists",
|
||||
},
|
||||
{
|
||||
"path": "specs/wizard-telegram-bot-cutover.md",
|
||||
"description": "Telegram cutover planning exists, so the migration lane is real",
|
||||
},
|
||||
],
|
||||
"missing_deliverables": [
|
||||
"wizard keypair inventory and ownership matrix",
|
||||
"NIP-29 relay group verification report",
|
||||
"operator runbook for cutting traffic off Telegram",
|
||||
],
|
||||
"why_open": "The repo has Nostr-adjacent scaffolding, but the directive still lacks a verified migration packet and the cited issue links drift away from the stated Nostr scope.",
|
||||
},
|
||||
{
|
||||
"key": "lexicon-enforcement",
|
||||
"name": "Lexicon Enforcement",
|
||||
"requirement": "Enforce the Fleet Lexicon in PR review and issue triage so the team uses one shared language.",
|
||||
"references": [388],
|
||||
"expected_keywords": ["lexicon", "vocabulary", "standards", "shared vocabulary"],
|
||||
"repo_evidence": [
|
||||
{
|
||||
"path": "docs/WIZARD_APPRENTICESHIP_CHARTER.md",
|
||||
"description": "The repo already uses wizard-language canon in docs",
|
||||
},
|
||||
{
|
||||
"path": "specs/timmy-ezra-bezalel-canon-sheet.md",
|
||||
"description": "Canonical agent naming already exists",
|
||||
},
|
||||
{
|
||||
"path": "docs/OPERATIONS_DASHBOARD.md",
|
||||
"description": "Operational roles are already described in repo language",
|
||||
},
|
||||
],
|
||||
"missing_deliverables": [
|
||||
"machine-checkable lexicon policy for review/triage",
|
||||
"terminology lint or reviewer checklist tied to the lexicon",
|
||||
],
|
||||
"why_open": "The naming canon exists, but there is still no executable enforcement bundle that would catch drift during future reviews and triage passes.",
|
||||
},
|
||||
{
|
||||
"key": "feature-audit",
|
||||
"name": "v0.7.0 Feature Audit",
|
||||
"requirement": "Audit Hermes features that can reduce cloud dependency and turn the findings into a sovereignty implementation plan.",
|
||||
"references": [139],
|
||||
"expected_keywords": ["hermes", "feature", "audit", "v0.7.0", "sovereignty"],
|
||||
"repo_evidence": [
|
||||
{
|
||||
"path": "scripts/sovereignty_audit.py",
|
||||
"description": "Cloud-vs-local audit machinery already exists",
|
||||
},
|
||||
{
|
||||
"path": "reports/evaluations/2026-04-15-phase-4-sovereignty-audit.md",
|
||||
"description": "Recent sovereignty audit report is committed",
|
||||
},
|
||||
{
|
||||
"path": "timmy-local/README.md",
|
||||
"description": "Local-first status is already documented for operators",
|
||||
},
|
||||
],
|
||||
"missing_deliverables": [
|
||||
"Hermes v0.7.0 feature inventory linked to cloud-reduction leverage",
|
||||
"Sovereignty Implementation Plan derived from that feature audit",
|
||||
],
|
||||
"why_open": "The repo has sovereignty-audit infrastructure, but it does not yet contain the requested v0.7.0 feature inventory or the plan that turns those findings into rollout steps.",
|
||||
},
|
||||
{
|
||||
"key": "morrowind-benchmark",
|
||||
"name": "Morrowind Local-First Benchmark",
|
||||
"requirement": "Compare cloud and local Morrowind agents, prove local parity where possible, and document the reasoning gap when it fails.",
|
||||
"references": [103],
|
||||
"expected_keywords": ["morrowind", "combat", "benchmark", "local", "cloud"],
|
||||
"repo_evidence": [
|
||||
{
|
||||
"path": "morrowind/local_brain.py",
|
||||
"description": "Local Morrowind control loop already exists",
|
||||
},
|
||||
{
|
||||
"path": "morrowind/mcp_server.py",
|
||||
"description": "Morrowind MCP control surface is already wired",
|
||||
},
|
||||
{
|
||||
"path": "morrowind/pilot.py",
|
||||
"description": "Trajectory logging for evaluation already exists",
|
||||
},
|
||||
],
|
||||
"missing_deliverables": [
|
||||
"cloud-vs-local benchmark report for the combat loop",
|
||||
"reasoning-gap writeup tied to a proposed LoRA/fine-tune path",
|
||||
],
|
||||
"why_open": "The repo has a local Morrowind stack, but it does not yet contain the requested benchmark artifact; the cited issue number also points at an unrelated caching task.",
|
||||
},
|
||||
{
|
||||
"key": "syntax-guard",
|
||||
"name": "Infrastructure Hardening / Syntax Guard",
|
||||
"requirement": "Verify Syntax Guard pre-receive protection across Gitea repos so syntax failures stop earlier.",
|
||||
"references": [],
|
||||
"expected_keywords": [],
|
||||
"repo_evidence": [],
|
||||
"missing_deliverables": [
|
||||
"repo inventory of Gitea targets that should carry Syntax Guard",
|
||||
"deployment verifier for hook presence across those repos",
|
||||
"operator report proving installation state instead of assuming it",
|
||||
],
|
||||
"why_open": "No repo-managed syntax-guard verifier is present yet, so this directive still depends on manual trust rather than auditable proof.",
|
||||
},
|
||||
]
|
||||
|
||||
|
||||
def default_snapshot() -> dict[int, dict[str, str]]:
|
||||
return deepcopy(DEFAULT_REFERENCE_SNAPSHOT)
|
||||
|
||||
|
||||
class GiteaClient:
|
||||
def __init__(self, token: str, owner: str = DEFAULT_OWNER, repo: str = DEFAULT_REPO, base_url: str = DEFAULT_BASE_URL):
|
||||
self.token = token
|
||||
self.owner = owner
|
||||
self.repo = repo
|
||||
self.base_url = base_url.rstrip("/")
|
||||
|
||||
def get_issue(self, issue_number: int) -> dict[str, Any]:
|
||||
req = request.Request(
|
||||
f"{self.base_url}/repos/{self.owner}/{self.repo}/issues/{issue_number}",
|
||||
headers={"Authorization": f"token {self.token}", "Accept": "application/json"},
|
||||
)
|
||||
with request.urlopen(req, timeout=30) as resp:
|
||||
return json.loads(resp.read().decode())
|
||||
|
||||
|
||||
def load_snapshot(path: Path | None = None) -> dict[int, dict[str, str]]:
|
||||
if path is None:
|
||||
return default_snapshot()
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
return {int(k): v for k, v in data.items()}
|
||||
|
||||
|
||||
def refresh_snapshot(token_file: Path = DEFAULT_TOKEN_FILE) -> dict[int, dict[str, str]]:
|
||||
token = token_file.read_text(encoding="utf-8").strip()
|
||||
client = GiteaClient(token=token)
|
||||
snapshot: dict[int, dict[str, str]] = {}
|
||||
for issue_number in sorted(DEFAULT_REFERENCE_SNAPSHOT):
|
||||
issue = client.get_issue(issue_number)
|
||||
snapshot[issue_number] = {
|
||||
"title": issue["title"],
|
||||
"state": issue["state"],
|
||||
}
|
||||
return snapshot
|
||||
|
||||
|
||||
def collect_repo_evidence(entries: list[dict[str, str]], repo_root: Path) -> tuple[list[str], list[str]]:
|
||||
present: list[str] = []
|
||||
missing: list[str] = []
|
||||
for entry in entries:
|
||||
label = f"`{entry['path']}` — {entry['description']}"
|
||||
if (repo_root / entry["path"]).exists():
|
||||
present.append(label)
|
||||
else:
|
||||
missing.append(label)
|
||||
return present, missing
|
||||
|
||||
|
||||
|
||||
def evaluate_reference(issue_number: int, snapshot: dict[int, dict[str, str]], expected_keywords: list[str]) -> dict[str, Any]:
|
||||
record = snapshot.get(issue_number, {"title": "missing from snapshot", "state": "unknown"})
|
||||
title = record["title"]
|
||||
title_lower = title.lower()
|
||||
matched_keywords = [kw for kw in expected_keywords if kw.lower() in title_lower]
|
||||
aligned = bool(matched_keywords) if expected_keywords else True
|
||||
return {
|
||||
"number": issue_number,
|
||||
"title": title,
|
||||
"state": record["state"],
|
||||
"aligned": aligned,
|
||||
"matched_keywords": matched_keywords,
|
||||
}
|
||||
|
||||
|
||||
|
||||
def classify_workstream(reference_results: list[dict[str, Any]], evidence_present: list[str], missing_deliverables: list[str]) -> str:
|
||||
has_drift = any(not item["aligned"] for item in reference_results)
|
||||
if not evidence_present:
|
||||
return "MISSING"
|
||||
if has_drift or missing_deliverables:
|
||||
return "PARTIAL"
|
||||
return "GROUNDED"
|
||||
|
||||
|
||||
|
||||
def evaluate_directive(snapshot: dict[int, dict[str, str]] | None = None, repo_root: Path | None = None) -> dict[str, Any]:
|
||||
snapshot = snapshot or default_snapshot()
|
||||
repo_root = repo_root or DEFAULT_REPO_ROOT
|
||||
workstreams: list[dict[str, Any]] = []
|
||||
drift_items: list[str] = []
|
||||
|
||||
for lane in WORKSTREAMS:
|
||||
reference_results = [
|
||||
evaluate_reference(issue_number, snapshot, lane["expected_keywords"])
|
||||
for issue_number in lane["references"]
|
||||
]
|
||||
present, missing = collect_repo_evidence(lane["repo_evidence"], repo_root)
|
||||
for item in reference_results:
|
||||
if not item["aligned"]:
|
||||
drift_items.append(
|
||||
f"#{item['number']} is cited for {lane['name']}, but its current title is '{item['title']}'."
|
||||
)
|
||||
workstream = {
|
||||
"key": lane["key"],
|
||||
"name": lane["name"],
|
||||
"requirement": lane["requirement"],
|
||||
"reference_results": reference_results,
|
||||
"repo_evidence_present": present,
|
||||
"repo_evidence_missing": missing,
|
||||
"missing_deliverables": list(lane["missing_deliverables"]),
|
||||
"why_open": lane["why_open"],
|
||||
}
|
||||
workstream["status"] = classify_workstream(
|
||||
reference_results=reference_results,
|
||||
evidence_present=present,
|
||||
missing_deliverables=workstream["missing_deliverables"],
|
||||
)
|
||||
workstreams.append(workstream)
|
||||
|
||||
next_actions: list[str] = []
|
||||
for workstream in workstreams:
|
||||
if workstream["missing_deliverables"]:
|
||||
next_actions.append(f"{workstream['name']}: {workstream['missing_deliverables'][0]}")
|
||||
|
||||
return {
|
||||
"issue_number": 524,
|
||||
"title": DIRECTIVE_TITLE,
|
||||
"summary": DIRECTIVE_SUMMARY,
|
||||
"reference_snapshot": {str(k): v for k, v in sorted(snapshot.items())},
|
||||
"workstreams": workstreams,
|
||||
"reference_drift": drift_items,
|
||||
"grounded_workstreams": sum(1 for item in workstreams if item["status"] == "GROUNDED"),
|
||||
"partial_workstreams": sum(1 for item in workstreams if item["status"] == "PARTIAL"),
|
||||
"missing_workstreams": sum(1 for item in workstreams if item["status"] == "MISSING"),
|
||||
"next_actions": next_actions,
|
||||
}
|
||||
|
||||
|
||||
|
||||
def render_markdown(result: dict[str, Any]) -> str:
|
||||
lines = [
|
||||
f"# {result['title']}",
|
||||
"",
|
||||
"Grounding report for `timmy-home #524`.",
|
||||
"",
|
||||
result["summary"],
|
||||
"",
|
||||
"This remains a `Refs #524` artifact. The directive spans multiple repos and operator actions, so this report makes the current repo-side state executable without pretending the whole migration is complete.",
|
||||
"",
|
||||
"## Directive Snapshot",
|
||||
"",
|
||||
f"- Repo-grounded workstreams: {result['grounded_workstreams']}",
|
||||
f"- Partial workstreams: {result['partial_workstreams']}",
|
||||
f"- Missing workstreams: {result['missing_workstreams']}",
|
||||
f"- Drifted references: {len(result['reference_drift'])}",
|
||||
"",
|
||||
"## Reference Drift",
|
||||
"",
|
||||
]
|
||||
if result["reference_drift"]:
|
||||
lines.extend(f"- {item}" for item in result["reference_drift"])
|
||||
else:
|
||||
lines.append("- No stale cross-links detected in the directive snapshot.")
|
||||
|
||||
lines.extend(["", "## Workstream Matrix", ""])
|
||||
for index, workstream in enumerate(result["workstreams"], start=1):
|
||||
lines.extend(
|
||||
[
|
||||
f"### {index}. {workstream['name']} — {workstream['status']}",
|
||||
"",
|
||||
f"- Requirement: {workstream['requirement']}",
|
||||
]
|
||||
)
|
||||
if workstream["reference_results"]:
|
||||
lines.append("- Referenced issues:")
|
||||
for ref in workstream["reference_results"]:
|
||||
alignment = "aligned" if ref["aligned"] else "DRIFT"
|
||||
lines.append(
|
||||
f" - #{ref['number']} ({ref['state']}) — {ref['title']} [{alignment}]"
|
||||
)
|
||||
else:
|
||||
lines.append("- Referenced issues: none listed in the directive body")
|
||||
|
||||
if workstream["repo_evidence_present"]:
|
||||
lines.append("- Repo evidence present:")
|
||||
lines.extend(f" - {item}" for item in workstream["repo_evidence_present"])
|
||||
else:
|
||||
lines.append("- Repo evidence present: none")
|
||||
|
||||
if workstream["repo_evidence_missing"]:
|
||||
lines.append("- Repo evidence expected but missing:")
|
||||
lines.extend(f" - {item}" for item in workstream["repo_evidence_missing"])
|
||||
|
||||
if workstream["missing_deliverables"]:
|
||||
lines.append("- Missing operator deliverables:")
|
||||
lines.extend(f" - {item}" for item in workstream["missing_deliverables"])
|
||||
else:
|
||||
lines.append("- Missing operator deliverables: none")
|
||||
|
||||
lines.append(f"- Why this lane remains open: {workstream['why_open']}")
|
||||
lines.append("")
|
||||
|
||||
lines.extend(["## Highest-Leverage Next Actions", ""])
|
||||
lines.extend(f"- {item}" for item in result["next_actions"])
|
||||
|
||||
lines.extend(
|
||||
[
|
||||
"",
|
||||
"## Why #524 Remains Open",
|
||||
"",
|
||||
"- The directive bundles five separate workstreams with different evidence surfaces.",
|
||||
"- Multiple cited issue numbers have drifted away from the work they are supposed to anchor.",
|
||||
"- Repo scaffolding exists for Nostr, sovereignty audits, and Morrowind, but the operator-facing bundles are still missing.",
|
||||
"- Syntax Guard verification is still undocumented and unproven inside this repo.",
|
||||
]
|
||||
)
|
||||
|
||||
return "\n".join(lines).rstrip() + "\n"
|
||||
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description="Render the unified fleet sovereignty status report for issue #524")
|
||||
parser.add_argument("--snapshot", help="Optional JSON snapshot file overriding the default issue-title/state snapshot")
|
||||
parser.add_argument("--live", action="store_true", help="Refresh the issue snapshot from Gitea before rendering")
|
||||
parser.add_argument("--token-file", default=str(DEFAULT_TOKEN_FILE), help="Token file used with --live")
|
||||
parser.add_argument("--output", help="Optional path to write the rendered report")
|
||||
parser.add_argument("--json", action="store_true", help="Print computed JSON instead of markdown")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.live:
|
||||
snapshot = refresh_snapshot(Path(args.token_file).expanduser())
|
||||
else:
|
||||
snapshot = load_snapshot(Path(args.snapshot).expanduser() if args.snapshot else None)
|
||||
|
||||
result = evaluate_directive(snapshot=snapshot, repo_root=DEFAULT_REPO_ROOT)
|
||||
rendered = json.dumps(result, indent=2) if args.json else render_markdown(result)
|
||||
|
||||
if args.output:
|
||||
output_path = Path(args.output).expanduser()
|
||||
output_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
output_path.write_text(rendered, encoding="utf-8")
|
||||
print(f"Directive status written to {output_path}")
|
||||
else:
|
||||
print(rendered)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,77 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
SCRIPT_PATH = ROOT / "scripts" / "unified_fleet_sovereignty_status.py"
|
||||
DOC_PATH = ROOT / "docs" / "UNIFIED_FLEET_SOVEREIGNTY_STATUS.md"
|
||||
|
||||
|
||||
def _load_module(path: Path, name: str):
|
||||
assert path.exists(), f"missing {path.relative_to(ROOT)}"
|
||||
spec = importlib.util.spec_from_file_location(name, path)
|
||||
assert spec and spec.loader
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
def _workstream(result: dict, key: str) -> dict:
|
||||
for workstream in result["workstreams"]:
|
||||
if workstream["key"] == key:
|
||||
return workstream
|
||||
raise AssertionError(f"missing workstream {key}")
|
||||
|
||||
|
||||
def test_evaluate_directive_flags_reference_drift_without_faking_completion() -> None:
|
||||
mod = _load_module(SCRIPT_PATH, "unified_fleet_sovereignty_status")
|
||||
result = mod.evaluate_directive(snapshot=mod.default_snapshot(), repo_root=ROOT)
|
||||
|
||||
assert len(result["reference_drift"]) == 4
|
||||
assert any("#813" in item for item in result["reference_drift"])
|
||||
assert any("#103" in item for item in result["reference_drift"])
|
||||
|
||||
nostr = _workstream(result, "nostr-migration")
|
||||
assert nostr["status"] == "PARTIAL"
|
||||
assert any("timmy_client.py" in item for item in nostr["repo_evidence_present"])
|
||||
|
||||
lexicon = _workstream(result, "lexicon-enforcement")
|
||||
assert all(item["aligned"] for item in lexicon["reference_results"])
|
||||
assert lexicon["status"] == "PARTIAL"
|
||||
|
||||
syntax_guard = _workstream(result, "syntax-guard")
|
||||
assert syntax_guard["status"] == "MISSING"
|
||||
assert any("deployment verifier" in item for item in syntax_guard["missing_deliverables"])
|
||||
|
||||
|
||||
def test_render_markdown_includes_required_sections_and_grounding_evidence() -> None:
|
||||
mod = _load_module(SCRIPT_PATH, "unified_fleet_sovereignty_status")
|
||||
result = mod.evaluate_directive(snapshot=mod.default_snapshot(), repo_root=ROOT)
|
||||
report = mod.render_markdown(result)
|
||||
|
||||
for snippet in (
|
||||
"# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration",
|
||||
"## Directive Snapshot",
|
||||
"## Reference Drift",
|
||||
"## Workstream Matrix",
|
||||
"### 5. Infrastructure Hardening / Syntax Guard — MISSING",
|
||||
"`infrastructure/timmy-bridge/client/timmy_client.py`",
|
||||
"machine-checkable lexicon policy for review/triage",
|
||||
"## Why #524 Remains Open",
|
||||
):
|
||||
assert snippet in report
|
||||
|
||||
|
||||
def test_repo_contains_committed_issue_524_grounding_doc() -> None:
|
||||
assert DOC_PATH.exists(), "missing committed directive grounding doc"
|
||||
text = DOC_PATH.read_text(encoding="utf-8")
|
||||
for snippet in (
|
||||
"# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration",
|
||||
"## Reference Drift",
|
||||
"## Workstream Matrix",
|
||||
"## Highest-Leverage Next Actions",
|
||||
"## Why #524 Remains Open",
|
||||
):
|
||||
assert snippet in text
|
||||
Reference in New Issue
Block a user