Heimdall/AGENTS.md
Meta Vens 96512ddabd Make AGENTS.md paths repo-relative so a drive move stops rotting it
Every path in Important Paths, Useful Commands, and External Context named the
lost E: drive. CLAUDE.md is a bare @AGENTS.md import, so those dead paths were
loaded into every session in this repo.

Swapping E: for F: would only reset the timer, so the paths are now
repo-relative and gamecult-ops is named as a sibling repo rather than an
absolute location. All ten referenced files were confirmed present after the
move; none were lost with the drive.

The interpreter guidance was worse than stale. It pointed at a venv under the
dead drive, and the documented fallback did not work either: this workstation
had no Python at all, and both `python` and `python3` resolved to Microsoft
Store aliases that print an install prompt and exit 0. Python 3.13.15 is now
installed to the user scope and ahead of WindowsApps on PATH, both tools were
run under it, and the section documents that failure mode so the next agent
installs an interpreter instead of hard-coding a path to someone else's.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 01:13:19 +02:00

5.3 KiB

Heimdall Instructions

Project Purpose

Heimdall exists to hold the shared auth authority design for GameCult-hosted experiments without letting that shared layer metastasize into a giant mixed-data pit.

The planned shared authority owns:

  • provider OAuth and linking
  • signed session / claim issuance
  • entitlement refresh
  • capability evaluation
  • app-facing access claims
  • audit and grant surfaces

The planned non-shared-by-default layer is:

  • app-domain user data
  • audience data
  • creator data
  • queue/job payloads
  • product-specific state
  • app-local resource ownership checks

Canonical State

  • Treat state/map.yaml as the canonical current project map.
  • Treat state/scratch.md as disposable working memory for one bounded subgoal.
  • Treat state/evidence.jsonl as the distilled durable ledger of decisions, verified boundaries, and rejected paths.
  • Treat state/branches.json as hypothesis tracking, not phase/status prose.
  • Treat notes/fresh-workspace-handoff.md as the compact re-entry packet.
  • Treat docs/architecture.md as the source-grounded shared architecture note.
  • Treat docs/implementation-plan.md as the forward plan.
  • Treat docs/app-profiles/repixelizer.md and docs/app-profiles/streampixels.md as thin app bindings, not the whole shared architecture. Add new app-profile notes when a new app binding needs durable context.

Important Paths

Paths are relative to the repository root. Do not hard-code an absolute drive path into this file; the repo has already been moved between drives once, and every absolute path in here rotted the moment it happened.

  • Shared architecture: docs/architecture.md
  • Implementation plan: docs/implementation-plan.md
  • Repixelizer profile: docs/app-profiles/repixelizer.md
  • StreamPixels profile: docs/app-profiles/streampixels.md
  • Spotiverse profile: docs/app-profiles/spotiverse.md
  • Handoff summary: notes/fresh-workspace-handoff.md
  • State CLI: tools/heimdall_state.py
  • Pre-compaction helper: tools/heimdall_prepare_compaction.py

Useful Commands

Both state tools are single-file, standard-library-only Python. They need no virtualenv and no installed dependencies. Run them with python from the repo root:

python .\tools\heimdall_state.py status
python .\tools\heimdall_state.py add-evidence --type design --status accepted --note "..."
python .\tools\heimdall_prepare_compaction.py

Verified 2026-09-06 against Python 3.13.15 installed to the user scope; py -3 resolves the same interpreter.

If python --version prints an install prompt rather than a version, PATH is resolving the Microsoft Store alias in WindowsApps instead of a real interpreter, and it will still exit 0 while doing so. Install a real Python and put it ahead of WindowsApps on PATH rather than hunting for some other interpreter to hard-code here:

winget install --id Python.Python.3.13 --scope user

Session Bootstrap And Re-entry Protocol

On fresh session load:

  1. read:
    • state/map.yaml
    • notes/fresh-workspace-handoff.md
    • docs/architecture.md
    • docs/implementation-plan.md
  2. run:
    • python .\tools\heimdall_state.py status
    • git status --short --branch
    • git log --oneline -5
  3. restate the current next action from persisted state before editing

After compaction or suspicious continuity loss:

  1. rerun heimdall_state.py status
  2. reread state/map.yaml and notes/fresh-workspace-handoff.md
  3. treat the persisted next action as authoritative unless fresh evidence contradicts it

When the user says to prepare for imminent compaction:

  1. run tools/heimdall_prepare_compaction.py
  2. update only the state that actually changed
  3. rerun the helper
  4. commit the completed persistence pass unless the work is deliberately mid-surgery

After any major completed pass, assume compaction may be imminent even if the user did not say so yet:

  1. run tools/heimdall_prepare_compaction.py
  2. sync only the persistent state that genuinely changed
  3. rerun the helper
  4. commit the persistence pass before moving on unless the work is deliberately mid-surgery
  5. push the current branch to origin after the major pass unless the user explicitly says not to publish yet

Operating Discipline

  • Before substantial edits, restate the current mechanism and intended change.
  • Keep identity authority central and app-domain data local unless there is a very deliberate, source-grounded reason to share something.
  • Prefer the Yggdrasil-hosted Heimdall service over duplicated per-app provider stacks.
  • Do not require a Heimdall round-trip for every guarded app route; host apps should verify signed claims locally and keep resource ownership checks local.
  • Do not let app profiles turn into duplicate copies of the shared architecture.
  • If the diff grows while the boundary gets blurrier, stop and simplify.
  • Before handoff or compaction, sync state/map.yaml, refresh notes/fresh-workspace-handoff.md, add distilled evidence when future belief changed, and make the next action explicit.

External Context

  • For StreamPixels architecture/auth context, prefer the indexed StreamPixels repo through voidbot before filesystem spelunking.
  • For GameCult deployment and host conventions, check the sibling gamecult-ops repo in the same projects root as this one before improvising infra claims.