@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/skills/galdr-ymirsystem/assets/build-method.md

@@ -0,0 +1,113 @@
+# Galdr Build Method — build, maintain, and forge
+
+The repeatable procedure for building or maintaining any part of Ymir, and the
+gates a new skill must pass to be "forged". Load this when building, porting, or
+extending the runtime or a skill.
+
+## Asset map (load the row that matches the task)
+
+```
+build_assets[6]{step,asset}:
+  "runtime spec","assets/brokk-distro-runtime.md"
+  "harness guide","assets/harness-integration/<harness>.md"
+  "component interfaces","assets/runtime-components.md"
+  "naming law","assets/norse-naming.md"
+  "porting","assets/porting-upstream-to-norse.md"
+  "acceptance gates","assets/runtime-compliance.md"
+```
+
+## The build method (repeatable, per harness)
+
+1. **Read the runtime spec** — `assets/brokk-distro-runtime.md` (home layout, digest,
+   lock, supervision, cron, worker model).
+2. **Check the harness guide** — `assets/harness-integration/<harness>.md` for the
+   exact hook surface, event names, and file paths.
+3. **Reuse the runtime scripts** — the harness adapter never reimplements the digest,
+   the lock, the watcher, or the guard; it invokes `bin/saga-session-start.sh`,
+   `bin/saga-sessionstart-run.sh`, `bin/syn-watch-arm.sh`, `bin/syn-turnend-guard.sh`,
+   `bin/rodd-operational-input.sh`, `bin/gleipnir-lock-lib.sh`.
+4. **Wire the contract** — session-open injection (run or nudge tier), watch arm,
+   turn-end guard, pretool seatbelts.
+5. **Bind the lock to the live session** — pass `BROKK_SESSION_PID` so Gleipnir holds
+   the harness process, not the short-lived digest helper.
+6. **Fail closed** — never launch on an unverified harness; a missing dependency is a
+   blocker, never a silent fallback.
+7. **Verify** — `bash -n` every shell file, parse every JSON, smoke-test the chain,
+   and run the checklist in `assets/runtime-compliance.md`.
+
+## Harness matrix (authoritative names)
+
+```
+harnesses[6]{harness,surface,tier,figures}:
+  "OpenCode","`.opencode/plugins/saga-sessionstart.js`, `syn-watch-arm.js`, `syn-turnend-guard.js`, `syn-pretool-check.js`, `syn-cd-check.js`","run","Sága+Sýn"
+  "Pi","`.pi/extensions/syn-turnend-guard.ts`, `gna-pi-watch.ts` (+ Vörðr supervisor)","run","Sága+Sýn+Gná+Vörðr"
+  "Claude Code","`.claude/settings.json` SessionStart + Stop","run","Sága+Sýn"
+  "Cursor","`.cursor/hooks.json` sessionStart + stop + preToolUse","run","Sága+Sýn"
+  "Codex","`.codex/hooks.json` SessionStart + PreToolUse + Stop (`[features].hooks=true`)","run","Sága+Sýn"
+  "Grok","not yet implemented","—","—"
+```
+
+Details, gotchas, and verification per harness: `assets/harness-integration/`.
+
+## Porting a validated upstream distro
+
+Prefer **copy-then-edit** over rebuild; the upstream carries edge cases you would
+otherwise re-derive. Follow `assets/porting-upstream-to-norse.md`: audit coupling,
+strip presentation and non-ported branches, retarget names/env/paths, bind the lock,
+defer the rest, then verify. Never rename our components after the upstream.
+
+## Maintenance rule
+
+When the runtime changes, update the owning asset in the same pass.
+
+**Every platform layer moves with the core.** Ymir is Omarchy-first but the core
+is portable (Linux, macOS, Windows/WSL2), and each platform may carry its own
+installation layer — see `RULES/05-platforms.md`. A core change is not complete
+until each layer has been checked against it and either updated in the same
+change or explicitly recorded as unaffected. A layer still installing the old
+shape is drift: a machine that boots expecting a runtime it no longer has.
+ Galdr assets are
+the system's memory: a runtime change that is not reflected in `assets/` is an
+incomplete change. Tyr judges both the code and the asset for drift.
+
+## Forge verification (six gates, gated by tyr-check)
+
+Before a new Galdr skill is considered "forged", it must pass these six gates, with
+asset references:
+
+```
+forge_gates[6]{id,gate,asset}:
+  1,"TOON output test — stdout TOON, ~40% smaller than JSON across 3 samples","schemas/toon-schemas.md"
+  2,"Principle compliance — all 10 principles assessed","assets/principles.md"
+  3,"Norse name validity — follows the aett pattern","assets/norse-naming.md, assets/registry.md"
+  4,"Frame integration — SKILL.md in `.agents/skills/<name>/`, referenced in the README; briefing notes it","assets/registry.md"
+  5,"Mimirsbrunn observation — creation observed into the well before live","POST /observe"
+  6,"PI primary compatibility — works under Hamr, emits rodd, Utgard-compliant, herdr-integrated","assets/pi-boot-guide.md"
+```
+
+Once all six gates pass, the skill is "forged" — it joins the library of the halls
+and is available via `npx skills add <owner>/<repo> --skill <name>` or as a managed
+plugin in `.config/opencode/plugins/`.
+
+## Acceptance summary (master builder)
+
+A Galdr-managed build is accepted only when all hold:
+
+```
+acceptance[7]{id,gate}:
+  1,"Comprehensive & reusable — assets/README.md routes every task"
+  2,"Norse methodology enforced — role-matched names; operator is the Allfather"
+  3,"Every harness documented and wired under assets/harness-integration/"
+  4,"Runtime contract honored — injection, lock binding, guard inert-until-armed"
+  5,"Production, no mocks — no examples/placeholders in the shipped runtime"
+  6,"Verified — bash -n clean, JSON parses, smoke evidence, compliance checklist"
+  7,"No drift — plan, code, and assets agree (Tyr's drift judgment)"
+```
+
+Full gates and runnable checks: `assets/runtime-compliance.md`.
+
+## Maintaining this
+
+- **Owner:** Brokk. **Router:** `.agents/skills/galdr-ymirsystem/SKILL.md`.
+- **Mirror:** `.agents/skills/tyr-check/assets/build-method.md`.
+- Update the asset map and harness matrix whenever a component or harness changes.

package/.agents/skills/galdr-ymirsystem/assets/build-tool-categories.md

@@ -0,0 +1,178 @@
+# Galdr Build Tool Categories
+
+Galdr needs to understand these build tool categories and their asset requirements for proper skill synthesis and compliance checking.
+
+## 1. Python Smíðja Tools
+
+**Location**: `templates/smidja/` (deterministic Python scripts that own sequencing/retries/acceptance)
+
+**Key Files**:
+- `smidja_*.py` — Orchestrator scripts (smidja_simple_sdlc, smidja_orchestrate, etc.)
+- `smidja_modules/data_types.py` — Pydantic v2 data types and data contracts
+- `smidja_modules/tracer.py` — SQLite WAL + JSONL events for tracing
+- `smidja_modules/quality.py` — Deterministic subprocess runs for quality gates
+- `smidja_modules/permissions.py` — Path-based write enforcement
+- `smidja_modules/agents.py` — Context handoff, sub-agent lane materialization (G2)
+- `agent_pi.py` — Pi agent runtime
+- `agent_opencode.py` — OpenCode agent runtime
+
+**Assets Galdr Needs**:
+- Tool schemas for smidja module data types
+- Quality gate validation patterns
+- Permission enforcement rules
+- Context handoff format specifications
+- Sub-agent task packet structures
+
+## 2. Command-Smíðja (Reuse OSS)
+
+**Validated OSS project**: `smidja` (disler-style "Smíðja")
+
+**Features**:
+- Deterministic Python owns graph, agents bounded nodes
+- Typed JSON envelopes carry context
+- Everything streams into SQLite for the polled visualizer
+- Vue visualizer served at port 8437 (API + built UI; `apps/visualizer/`)
+
+**Assets Galdr Needs**:
+- Smíðja script patterns
+- JSON envelope schemas
+- SQLite telemetry structure
+- Visualizer data format
+
+## 3. Brokk Crew Orchestration
+
+**External agent distro**: kunchenguid's Brokk
+
+**Features**:
+- One Allfather talks to first mate running autonomous coding agents
+- Agents in tmux panes on git worktrees
+- Project modes: no-mistakes/direct-PR/local-only/+yolo
+- Crew orchestration, worktree isolation (Yggdrasil/orca)
+- Restart-proof disk state, supervision watcher
+- X/Discord Relay, eindri-homes
+
+**Assets Galdr Needs**:
+- Worktree isolation patterns
+- tmux pane management schemas
+- Restart-proof disk state format
+- Supervision watcher patterns
+
+## 4. Galdr Skill Assets (Internal)
+
+**Location**: `.agents/skills/galdr-ymirsystem/assets/`
+
+**Purpose**: Reference data for skill synthesis and compliance checking
+
+**Contents**:
+- Eindri sub-agent profiles (see eindri-profiles.md)
+- Tool-specific TOON output schemas
+- Norse naming aett patterns
+- Utgard sandbox compliance checklists
+- Session integration hooks
+
+## Tool-Specific TOON Schemas
+
+Galdr references these TOON output schemas per tool type:
+
+### Smíðja Orchestrator (Python)
+```toon
+smidja:
+  status: open|closed|in-progress
+  phase: <phase-name>
+  progress: 0-100
+  next_action: <action-description>
+  utgard_sandbox: true
+  worktree: <branch-name>
+```
+
+### Brokk Allfather
+```toon
+crew:
+  status: active|paused|completed
+  agent_role: <developer|marketer|researcher>
+  worktree: <branch-name>
+  utgard: true
+  sandboxed: true
+```
+
+### Galdr Skill Generator
+```toon
+skill:
+  name: <norse-skill-name>
+  category: <feature|bug|infrastructure|compliance|system>
+  toon_output: true
+  principles: [1,2,3,4,5,6,7,8,9,10]
+  compliance_status: validated|pending
+```
+
+## Norse Aett Pattern Reference
+
+All new Galdr skills follow this naming aett (family of eight):
+
+| Aett Name | Pattern | Examples |
+|-----------|---------|--------|
+| **galdr-** | incantation / chant standards | `galdr`, `tyr-check` |
+| **val-** | hall / health | `valhalla` (process monitor) |
+| **skyr-** | giant / file scope | `skrymir` (file browser) |
+| **bifr-** | bridge / gateway | `bifrost` (gateway/proxy) |
+| **heimd-** | gate / guard | `heimdall` (auth/security) |
+| **gjallar-** | horn / signal | `gjallarhorn` (cloudflared tunnel) |
+| **mimir-** | memory / wisdom | (planned) |
+| **yggd-** | tree / worktree | (planned) |
+
+## Utgard Sandbox Compliance Checklist
+
+Every Galdr-generated CLI tool must declare:
+
+```
+[runs_in_utgard: true]
+[utgard_network: none]
+[utgard_resource_caps: true]
+[yggdrasil_worktree: true]
+[sandboxed: true]
+```
+
+Failure to declare all five results in compliance gate rejection.
+
+## Session Integration Hooks
+
+Galdr references these hook patterns:
+
+### Primary: Session Hook
+- Installs/repairs after user intent is clear
+- Provides compact dashboard as context at session start
+- Loads on every session
+- Works only in agents that support hooks
+
+### Secondary: Installable Skill
+- Loads on demand when agent recognizes matching task
+- No per-session token cost
+- Works in any agent that supports skill format
+- Recommended: hook first, skill second (complementary)
+
+### Hook Command Pattern
+```
+provide_explicit_setup_command that installs or repairs a session hook or plugin after user intent is clear
+at_session_start the integration runs your tool and provides a compact dashboard as context
+agent receives this as initial context and can act immediately
+```
+
+## Compliance Gate Asset References
+
+| Asset File | Path | Purpose |
+|------------|------|---------|
+| Eindri profiles | `.agents/subagents/*.md` | Sub-agent role definitions |
+| Tool schemas | `.agents/skills/galdr-ymirsystem/schemas/` | TOON output formats per tool |
+| Workspace patterns | `.agents/skills/galdr-ymirsystem/assets/` | Workspace directory conventions |
+| Aett pattern | `.agents/skills/galdr-ymirsystem/assets/` | Norse naming convention |
+| Compliance requirements | `.agents/skills/galdr-ymirsystem/assets/compliance-requirements.md` | Five Utgard sandbox gates |
+
+## Usage in Skill Synthesis
+
+When a skill is forged, it:
+1. References Eindri profiles from `.agents/subagents/*.md`
+2. Assigns appropriate aett naming from the Norse pattern table
+3. Generates TOON output schema based on tool category
+4. Includes Utgard sandbox compliance declarations
+5. Adds session integration hook recommendations
+6. Validates against `tyr-check`'s principles checklist