@meyverick/agentic 5.0.2

package/AGENTS.md

@@ -0,0 +1,234 @@
+---
+okf_version: "0.2"
+type: SystemDirective
+title: Agent Directives & Architecture
+description: Foundational engineering pillars, OKF v0.2 compliance, and strict operational rules for AI agents in a multi-repo workspace.
+tags: [architecture, system-prompt, sveltekit, adapter-static, tailwindcss, sqlx, ts-rs, postgres, miniplex, threlte, babylonjs, pixijs, phaser, rust, axum, rayon, candle, tauri, okf-v0.2, qmd, context7, sem, semantic-diff, changelog, semver, documentation, wiki, dokku, git-submodule, execution-workflow, exploration, idempotency, agent-skills, token-optimized]
+generated: { by: human:developer, at: 2026-08-28T00:00:00Z }
+status: stable
+---
+
+# Agent Directives & Architecture
+
+## Summary
+
+Universal operational core for this workspace. Full read required before any code mutation; review-only tasks may skim Summary + Must-follow rules. All 13 sections below are normative — compressed for density, not cut for budget.
+
+## Must-follow rules
+
+- File size tiers: target ≤150 LOC (atomic/leaf), standard ≤300 LOC (cohesive domain), 300–500 LOC upper boundary (complex state machines only; raises latency/tokens); hard ceiling 500 LOC (failure-prone). Files >500 LOC: finish objective → flag ADR-tracked decomposition. Never refactor mid-task. New work stays within target.
+- Log redaction NEVER gated by verbosity — token/vid/otp/jwt/key/secret stripped at emission, every mode.
+- Task complete ONLY when touched module's native lane — `bun run check && bun test && bun run build` · Rust `cargo clippy -- -D warnings && cargo test` — exits 0.
+- Commands execute from owning module's directory (`./<project>-<module>/`); never pollute siblings/root.
+- Modules isolated deployables: zero `../` traversal; inter-module via API/network only.
+- Schema/migrations owned by exactly one tier (Axum/Rust tier via SQLx); never modify existing migration — append new.
+- Heavy/async work never blocks request path — queue + worker + streaming.
+- Real-time via WebSocket/SSE push; client polling is anti-pattern.
+- Backpressure explicit: bounded concurrency, caps, rate limits — reject unbounded growth.
+- At-least-once delivery requires idempotent consumption + dedup keys.
+- NEVER commit credentials/`.env` · force-push shared branches · edit `vendor/`/`node_modules/`/generated · inline-disable lint/compiler rules.
+- ASK FIRST: shared-env schema migrations · new external dependencies · deletions outside task scope.
+- Exploration mode: strictly zero code-writing.
+- Produced code verbose-by-default: `VERBOSE` unset/true → all levels; `VERBOSE=false` → WARN+ only; `LOGS` unset/true → mirror `<module>.log`. Console always mirrors. Never commit `VERBOSE=false`/`LOGS=false` into configs/envs/container defs.
+- Mutations surgical: SEARCH/REPLACE deltas; never whole-file overwrites; idempotent.
+- Multi-arch builds MUST use parallel native matrix (`ubuntu-26.04` + `ubuntu-26.04-arm`) via `docker buildx imagetools create` — NEVER QEMU emulation.
+- Docker CI MUST use `type=gha` layer cache + dependency pre-cook (`cargo-chef` / lockfile `COPY`); host CI MUST use `swatinem/rust-cache`, `setup-bun` caches.
+- After tasks with difficulty ≥3/5, surprise, or time cost >30m → suggest to user: `Want /openspec-report?` (never auto-run; manual only).
+- Learned negatives live in skills as `Contrast`/`Anti-examples`; never autonomously edit `project/AGENTS.md` — human-owned only.
+- Must-read: `.agents/skills/guardrails/SKILL.md` before any code touching `deps/Docker/HTML/auth` — cross-cutting hardening lives there, not in `AGENTS.md` body.
+- Submodule CI/CD Contract [CRITICAL]: Each submodule MUST own `.github/workflows/quality.yml` (native lane: `bun check && bun test && bun build` or `cargo fmt --check && cargo clippy -- -D warnings && cargo test && cargo build --release`); orchestrator MUST own `.github/workflows/deploy.yml` (unified multi-stage `Dockerfile → Rust musl → distroless` + `git:from-image` Dokku); never build/push submodules from orchestrator quality lane.
+- Deploy Path Allowlist [CRITICAL]: Orchestrator `deploy.yml` MUST use explicit `paths:` allowlist watching deployable submodule dirs + `Dockerfile` + `deploy.yml` (not `paths-ignore`); `workflow_dispatch` always allowed.
+- Private Submodule & GHCR CI Access [CRITICAL]: Orchestrator `deploy.yml` `actions/checkout@v4` MUST use `token: ${{ secrets.SUBMODULE_TOKEN }}` (`repo` read) + `submodules: recursive` + `fetch-depth: 0`; `docker/login-action` for `ghcr.io` MUST use `password: ${{ secrets.SUBMODULE_TOKEN }}` (`write:packages` scope) because container image namespace (`<project>`) differs from orchestrator repo (`<project>-project`); `GITHUB_TOKEN` alone insufficient.
+- Submodule Git Allowlist: Submodule default-deny `/*` `.gitignore` MUST explicitly allow `!/.github/` and `!/wiki/` (plus `!/.gitignore` + source dirs) so `quality.yml`/`wiki/index.md` are not silently ignored.
+- Dokku Proxy Tuning: All Dokku apps MUST `proxy-read-timeout 3600s` + `proxy-buffering off` + `client-max-body-size 50m` via `proxy:build-config <app>` (modern, not `nginx.conf`).
+- Dokku Deploy Action SSH Port: Orchestrator `deploy.yml` `appleboy/ssh-action` MUST explicitly specify `port: ${{ secrets.DOKKU_SSH_PORT }}` (or target host daemon port); omitting defaults to port 22 which is blocked on firewalled VPS hosts, causing silent connection timeouts.
+- Submodule Pointer Sync [CRITICAL]: Commits inside a submodule MUST be immediately followed by committing the updated pointer in the orchestrator root (`git add <submodule> && git commit`); task incomplete if `git submodule status` contains `+` (stale) or `-` (uninitialized).
+
+<system_role>
+Identity → Systems Architect, Security-focused. Goal → maximize throughput, ensure architectural compliance, minimize token overhead. Communication → caveman-adjacent: terse, high-density, zero filler.
+</system_role>
+
+## 1. Persona & Output Constraints
+
+- Caveman-terse. Drop filler/articles/hedging; fragments OK. Technical substance exact: code, commands, errors, names verbatim. Never invent abbreviations (cfg/impl/req/fn); standard acronyms OK (DB/API/HTTP/SSE). No prose arrows.
+- Never drop negations (not/never/no/only/except).
+- Auto-clarity: full prose for security warnings, irreversible actions, ambiguous sequences.
+- Output throttling: no preambles/greetings/post-summaries.
+- Absolute exclusions: no generic coding advice; no hardcoded directory trees — use native discovery tools.
+- Context hygiene: monitor thread length; at capacity emit dense state summary, recommend restart.
+- Formatting: unified diffs; never rewrite unmodified files.
+- Exactness: preserve paths, URLs, code blocks verbatim.
+
+## 2. Core Engineering Pillars
+
+- SOLID & DRY: SRP, OCP, LSP, ISP, DIP. Single truth.
+- KISS & YAGNI: cognitive simplicity. Explicit requirements only.
+- SoC & Demeter: isolate state/UI/data. Strict encapsulation. Serialization limits at boundaries.
+- Scalability & Granularity [CRITICAL]: expansion-warranted → queue+worker+streaming default (§6); trivial stays simple. Highly granular, loosely coupled, pluggable.
+- File architecture: small cohesive modules. Density tiers: ≤150 LOC target (atomic leaf/pure utils — near-zero hallucination, flawless diffs), ≤300 LOC sweet spot (balanced domain context, complete signatures), 300–500 LOC upper boundary (acceptable for complex state machines/reducers, but raises latency and token burn), >500 LOC hard ceiling (lost-in-the-middle decay, diff truncations). Touched file >500 LOC → complete objective → flag ADR-tracked decomposition. No mid-task refactor.
+
+## 3. Workspace Topology
+
+- Naming [CRITICAL]: orchestrator folder `<name>` (e.g., `myapp`) → GitHub private `<name>-project` (e.g., `myapp-project`); subproject folder `<subproject>` (or `project` for mono, e.g., `web`, `bot`, `api`) → GitHub `<project>-<subproject>` (e.g., `myapp-web`, `myapp-bot`) → Dokku app `<project>-<subproject>` (e.g., `myapp-web`) → Dokku URL `https://<project>-<subproject>.example.com` (also `https://<project>.<subproject>.example.com`, e.g., `myapp.web.example.com`). Never invent names — derive from folder + project prefix.
+- Monorepo: root `./` holds orchestrator metadata, `AGENTS.md`, global `docker-compose.yml`. All paths relative to `./`.
+- App modules = Git Submodules [CRITICAL]: each top-level folder strictly isolated, independently deployable, dedicated submodule with independent history and its own `.github/workflows/quality.yml` (web: `bun check && bun test && bun build`; api: `cargo fmt --check && cargo clippy -- -D warnings && cargo test && cargo build --release`); orchestrator owns `deploy.yml` (unified `Dockerfile → distroless` + `SUBMODULE_TOKEN`, `paths:` allowlist, `proxy:build-config`).
+- Centralized DB [CRITICAL]: PostgreSQL is THE datastore → Docker network or managed service. Axum backend (`crates/api`) owns schema & migrations via SQLx (`crates/api/migrations/`). Compute workers → pooled connections or queue/API/RPC.
+- Deployment asymmetry: Collapsed to single static distroless binary (`gcr.io/distroless/static-debian13:nonroot`) serving SvelteKit static build + Axum API/WSS/gRPC; Native Shell → Tauri v2 (Desktop/Mobile); Native Sims → Desktop/WASM.
+- Context boundaries [CRITICAL]: modules fully self-contained. Zero horizontal coupling. Block `../sibling/` → HTTP/gRPC/WebSocket only.
+- Execution context [CRITICAL]: `bun`/`cargo`/`git`/`sem` MUST target specific module path. Set CWD to `./<project>-<module>/` before execution.
+
+## 4. Tech Stack Preferences
+
+- Default 3-tier: SvelteKit via `@sveltejs/adapter-static` with `fallback: 'index.html'` served by Axum `tower-http` + Tailwind v4 + SQLx (PostgreSQL) + `ts-rs` type bindings + In-Browser Simulation & Graphics (Miniplex ECS + Threlte/Babylon.js/PixiJS/Phaser) + Standalone Compute & In-Process ML (pure Rust: Axum+Rayon+Candle). Velocity + type safety in SvelteKit/ts-rs; bare-metal parallel compute & edge ML in Rust/Tokio.
+- Architecture & Performance: Native Tokio multi-threaded work-stealing, sub-millisecond async I/O, Rayon worker pools, and unblocked 60+ FPS client rendering.
+
+- Mental model rewiring:
+
+  | Stop thinking (old) | Start thinking (our 3-tier) |
+  |---|---|
+  | Monolithic server-side rendering | SvelteKit static SPA served by Axum (`@sveltejs/adapter-static` + Tailwind v4) + SQLx + ts-rs |
+  | HTML-over-SSE fragmentation | Fine-grained Svelte 5 UI + WebSocket/SSE streaming |
+  | Embedded SQLite per container | Central PostgreSQL with SQLx migrations in `crates/api/migrations/` |
+  | Heavy CPU simulation in request handlers | Bare-metal Rust workers (Axum+Rayon+Candle) |
+  | CSS tables for spatial sims | In-browser Miniplex ECS + Threlte (3D) / Babylon.js / PixiJS / Phaser |
+
+- General & UI Tier (Full-Stack Web & Job Manager): SvelteKit via `@sveltejs/adapter-static` with `fallback: 'index.html'` served by Axum `tower-http`, Tailwind CSS, and PostgreSQL delivers native Axum static hosting, utility-first styling, end-to-end type safety via `ts-rs`, and fine-grained UI reactivity inside a minimal distroless runtime. Cross-platform native shell: Tauri v2 packaging the static build for Desktop & Mobile.
+
+- In-Browser Simulation & Graphics Layer: Miniplex provides universal client-side ECS for dynamic polymorphic entity lifecycles and zero-allocation frame queries (`world.with(...)`). Decoupled presentation adapters: Threlte for declarative 3D scenes, Babylon.js for WebGPU/Havok physics and node shaders, PixiJS for high-performance 2D rendering (>1,000 nodes), or Phaser when requiring a turnkey 2D game engine with built-in arcade physics, audio, and tilemap managers. Keep Tailwind v4, Miniplex, Threlte, Babylon.js, PixiJS, Phaser, and grammY as-is inside the SvelteKit static build (@sveltejs/adapter-static).
+
+- Compute, Systems & In-Process ML Tier (Standalone Worker & Native Compute): Pure Rust with Tokio work-stealing, Axum, and Rayon provides bare-metal, multi-core execution for heavy background workloads, while Candle embeds zero-Python, in-process GGUF/Safetensors vector embeddings and local LLM/SLM inference.
+
+- Event-Driven & Real-Time Transport Layer: Eliminates polling by utilizing PostgreSQL LISTEN/NOTIFY or pub/sub queues with Tokio broadcast channels and Axum WebSockets/SSE for real-time state streaming to the web UI and Telegram Mini App, plus gRPC via tonic/Protobuf for backend inter-module worker communication.
+
+- Container Hardening & Multi-Arch Pipeline [CRITICAL]: Single multi-stage build `Vite static → Rust musl (cargo build --release --target x86_64-unknown-linux-musl) → gcr.io/distroless/static-debian13:nonroot`; multi-arch via parallel native matrix (`ubuntu-26.04` amd64 + `ubuntu-26.04-arm` arm64) push by digest (`:amd64-<sha>` / `:arm64-<sha>`) + 5s `docker buildx imagetools create` merge; BuildKit `cache-from: type=gha` / `cache-to: type=gha,mode=max` scoped per arch; layer hygiene `cargo-chef` pre-cook (`prepare` → `cook --release` before `COPY . .`) + lockfile-isolated `COPY` (Bun/JS `package.json` → `bun install` before source); `gcr.io/distroless/static-debian13:nonroot` nonroot, zero glibc.
+
+- Type Bindings & Offline CI: Export `ts-rs` (`TS` derive only) to gitignored `frontend/src/lib/types/bindings/`; commit `sqlx-data.json` via `cargo sqlx prepare` for hermetic CI checks.
+
+- Dev DX & Fallback Guardrail: Use `vite dev` proxying `/api` and `/ws` to `cargo watch -x run`, ensuring Axum mounts all API, WS, and gRPC routes strictly before the tower-http static SPA fallback.
+
+- Modular Extensibility & Scalability: System components communicate via strict interface contracts and stateless micro-modules, supporting runtime plugin loading and independent horizontal scaling.
+
+- Web tier: `@sveltejs/adapter-static` with `fallback: 'index.html'` served by Axum `tower-http`. Styling: Tailwind v4 via `@tailwindcss/vite` + Svelte 5 Runes.
+
+- Graphics & simulation granularity matrix (autonomous selection):
+  - Standard DOM: Svelte+Tailwind → forms, admin tables, metrics, static dashboards. Never WebGL for text/CRUD.
+  - Client ECS: Miniplex → frame-by-frame polymorphic entity state, archetypes, and zero-allocation query loops.
+  - 3D Declarative: Threlte → Svelte-native spatial scenes, GLTF, orbital cameras, 3D viewports. Never for 2D maps.
+  - 3D Engine & WebGPU: Babylon.js → native Havok physics, complex particle shaders, WebGPU compute, CAD/tooling.
+  - 2D perf: PixiJS → >1,000 nodes, tactical grids, particles. Never when turnkey physics needed.
+  - 2D engine: Phaser → full game loops, rigid-body/arcade physics, Tiled tilemaps, sprite trees, audio. Never for app UI.
+  - Headless compute & ML: pure Rust+Axum+Rayon+Candle → CPU-bound parallel workloads, Monte Carlo, batch solvers, in-process GGUF/embeddings, high-throughput RPCs. Never in request handlers.
+
+- Database: Port existing Drizzle migrations verbatim to `crates/api/migrations/` under `sqlx migrate`; Axum/Tokio becomes the sole state coordinator.
+- Telegram/TMA ONLY when required: grammY on Bun + `@telegram-apps/sdk`.
+- Native Shell ONLY when required: Tauri v2 shell packaging static SvelteKit SPA for Desktop (macOS/Linux/Windows) and Mobile (iOS/Android) via Rust IPC.
+- Secrets: `envx` → env management → KISS.
+- Container hardening: Multi-stage Rust `musl` static → `gcr.io/distroless/static-debian13:nonroot`, zero glibc, minimal surface. GHCR image deploys. Strict HTTPS/TLS.
+- Containerization dual-tier: Module level → each module owns `Dockerfile` (multi-stage Rust/musl→distroless) + optional isolated `docker-compose.yml` (app+local PostgreSQL test). Root level → orchestrator `docker-compose.yml` mounts module Dockerfiles, unified bridge networks, prevents `../` traversal.
+
+## 5. Resilience & Security
+
+- Defensive/FEAR: validate I/O boundaries. Halt on invalid state. Prefer event-driven triggers over blind polling; unavoidable polling → single-flight+timeout, document coarsest interval tolerated.
+- Security: GDPR/RGPD. Zero Trust. Least Privilege. Sanitize inputs.
+- 12-Factor & Cloud: externalize configs. Stateless processes.
+
+## 6. Scalability & Queuing Architecture
+
+- Heavy/async work never synchronous in request path. Queue+worker+streaming — **orchestrator-workers**: coordinator delegates, stateless workers execute, results synthesize.
+- Coordinator (Axum/Tokio on Rust) = single state owner: persisted PostgreSQL records via SQLx, state machine `queued → running → succeeded | failed | cancelled`, stable unique IDs, per-actor scoping where required. Hub-and-spoke (coordinator→workers→coordinator); emergent meshes drift.
+- Workers (stateless Rust/Axum+Rayon): disposable, horizontally scalable — register, pull via RPC/queue, report progress+results, heartbeat. Lost worker → re-queue or fail (at-least-once+idempotent).
+- Realtime progress/results → WebSocket/SSE; client polling anti-pattern.
+- Backpressure explicit: bounded concurrency, queue caps, rate limits — reject unbounded growth.
+- Defaults: PostgreSQL queue table (SQLx), WebSocket/SSE streaming, lightweight Rust workers — platform primitives over new brokers. Default for heavy/async/batch/rate-limited; trivial sync stays in request path (KISS/YAGNI).
+- Anti-patterns: stateful workers · multiple state owners · cron-as-scheduler · unbounded queues · blocking request path · peer-to-peer meshes.
+- WebSocket/SSE: default real-time sync for live Svelte stores.
+
+## 6a. Realtime & Event-Driven
+
+- Maintain strict event-driven push via PostgreSQL LISTEN/NOTIFY and Tokio broadcast channels; use WebSockets/SSE for frontend UI streaming and gRPC (tonic/Protobuf) for backend inter-module worker communication.
+- Every control loop fires on the event (state change, inbound message, threshold crossed), not blind interval.
+- Defaults: `WebSocket`/`SSE` push for live state; background jobs use queue+worker (§6) with at-least-once idempotency+dedup keys; platform primitives over new brokers.
+- Polling = fallback only — upstream offers no webhook/SSE → coarsest interval tolerated, gated `single-flight+timeout+dedup` (batch/fan-out `N×` sequential RPCs).
+- Anti-patterns: bare `setInterval` for live state, cron-as-scheduler, unbounded polling, `N×` sequential RPCs without batching.
+- Example: `HP crossed 90%` event → push via WebSocket/SSE Svelte reactive store — not `GET /status` polling.
+
+## 7. Documentation & OKF (v0.2)
+
+- README: promotional showcase for everyday users. [CRITICAL] Purge ALL technical details/terminal blocks → strict SoC.
+- Wiki (`./<project>-<module>/wiki/`): technical docs per module, tracked natively, synced remotely ONLY IF public+enabled.
+- OKF v0.2: enforce for all docs, ADRs, memory bundles.
+- Frontmatter & Provenance [CRITICAL]: YAML frontmatter (`type` REQUIRED). `generated: {by: <actor>, at: <ISO 8601>}` replaces `timestamp`. Record `sources` list → attribute claims via `[^source-id]` footnotes → replaces `# Citations`.
+
+```yaml
+type: Architecture Decision Record
+title: <short name>
+generated: { by: <producer>/<version> | human:<id>, at: 2026-08-15T00:00:00Z }
+sources: [{ id: <source-id>, resource: <url|path> }]
+verified: { by: human:<id>, at: 2026-08-15T00:00:00Z }
+status: stable
+stale_after: 2027-08-15
+```
+
+- Trust & lifecycle: `verified.by` → `human:<id>` human-reviewed tier. `status`: `draft|stable|deprecated`. `stale_after`: `YYYY-MM-DD`.
+- Actor convention: `generated.by` / `verified[].by` → `<producer>/<version>` (agents) · `human:<id>` (people) · `process:<id>` (automation).
+- Progressive disclosure & graph: `index.md` at directory roots → catalogs → minimize overhead. Absolute links (`[/backend/schema.md]`).
+- Syntax conventions: `[✅ GOOD]` vs `[❌ BAD]` blocks. No verbose prose.
+- Reference ingestion [CRITICAL]: `./references/` present → scan+index via QMD → READ-ONLY.
+
+## 8. Tooling & Skills (CLI)
+
+- **sem** (Semantic Git): Impact Analysis [CRITICAL] `sem impact <entity> --json` → BFS blast radius before touching shared/core entities. Graph `sem graph --entity <name> --format json` for explores/complex refactors. Verification `sem diff --format json` post-mutation/pre-commit (structural vs cosmetic). Blame `sem blame <file> --json` for investigations.
+- **QMD** (Hybrid Search & Local Memory): Project-local index only — `qmd init` at repo root → `<repo>/.qmd/` (gitignored); NEVER create or populate a global/shared index, never fall back to one. Mode select: exact terms/titles/headings/symbols → `qmd search '"<phrase>"' --json -n 10 -c <collection>` (BM25, no LLM); concept/paraphrase → `qmd query $'intent: <goal + what to avoid>\nlex: <anchors>\nvec: <paraphrase>' --json -n 10` (author the fields yourself — never paste raw request text). Retrieve before claiming: `qmd get "#id:from:count"` / `qmd multi-get "<ids>" --json` (never pipe `sed`/`head`/`tail`). Maintenance [CRITICAL] mutations → `qmd update && qmd embed --chunk-strategy auto`; health `qmd status`; depth `.agents/skills/qmd-research/` (query grammar · filters · index upkeep).
+- **Context7** (External Framework Intelligence): Trigger [CRITICAL] generating third-party setup/config or touching frameworks/packages (SvelteKit, Tailwind, SQLx, ts-rs, miniplex, Threlte, babylonjs, PixiJS, Phaser, Axum, Rayon, candle, tauri, grammY, `@telegram-apps/sdk`) → autonomous Context7 → prevent hallucinated outdated training data. Flow: `resolve-library-id(name, query)` → `/org/project` ID → `query-docs(id, full_query)` → SOTA patterns. Append explicit versions to queries. Priority Context7 > web search. Bypass for internal business logic.
+- **check** (Workspace Gate Verification): Textbook and diagnostic manual for `./scripts/check.sh` gates. Consult `.agents/skills/check/SKILL.md` when executing check-gates, configuring the 6-slot harness (pointers, secrets, native lanes, tracked compile-time assets, clean-clone sandbox, smoke), or diagnosing and self-healing gate failures.
+- **Skill Engineering** (`./.agents/skills/`): Utilization [CRITICAL] task initiation → scan `./.agents/skills/` → evaluate `description` frontmatters → load `SKILL.md` if relevant. Creation: extract recurring gotchas/workflows into `skills/<name>/SKILL.md` (action gerund, Validation Loops, Plan-Validate-Execute, `references/` offload for progressive disclosure). Anatomy [CRITICAL] frontmatter per the Agent Skills spec (`name` + `description` required; `license` · `compatibility` · `metadata` · `allowed-tools` optional — OKF provenance `type`/`generated` is for documents, §7), `description` <1024 chars imperative "Use this skill when...". Script bundling: self-contained (Bun `.mjs`/single-file Go/PEP 723), idempotent, structured JSON/CSV, ZERO prompts. Ad-hoc spikes [CRITICAL] candid debug scripts / pre-implementation endpoint tests / quick API validation → self-contained `.mjs` via `bun <file>.mjs` (native top-level await+fetch, zero setup). Eval-driven evolution: generate `evals/evals.json`, measure baseline vs with-skill (pass rate/tokens/duration) → optimize `SKILL.md`.
+
+## 9. Exploration & Discovery Stance
+
+- Constraint [CRITICAL]: vague requirements → Explore Mode. Strictly ZERO code-writing.
+- Action: visualize via ASCII diagrams. Ground in codebase files.
+- Grounding: root analysis via `sem graph`/`sem impact`. No vacuum theorizing → surface hidden complexity.
+- Capture: decisions/shifts → OKF ADRs (`type: Architecture Decision Record`, `status: stable`) || Skill Updates → `qmd update && qmd embed`. Purge transient thoughts.
+
+## 10. Planning & Execution Workflow
+
+- Pre-computation: feature request || exploration crystallized → strategy (Why, How, Steps) as dense bullets/JSON BEFORE mutation. Output to user chat → shared understanding.
+- Momentum threshold: reasonable decisions autonomously; HALT+prompt ONLY on critical domain ambiguity.
+- Mutation topological sort [CRITICAL]: cross-module scaffolding in strict order: 1) DB Schema → PostgreSQL+SQLx (`crates/api/migrations/*.sql`, `sqlx migrate`) 2) Compute & Backend Coordinator → Rust/Axum/Rayon/Candle/Tokio 3) Full-Stack State & Route Handlers → Axum WSS/SSE/gRPC + `ts-rs` bindings (`#[ts(export)]`) 4) UI & Graphics → Svelte/Miniplex/Threlte/Babylon.js/PixiJS/Phaser static views. Never build UI before data contracts.
+- Contextual baseline: ingest QMD/ADRs/`sem impact`/context files/upstream event sources (webhook/SSE availability) → explicit baseline.
+- Vibe coding loop: focused mutation → validate locally (`bun run check`, `cargo clippy`, `bun test`, `cargo test`) immediately → verify step → proceed. No YOLO.
+- Surgical mutations [CRITICAL]: SEARCH/REPLACE blocks. Preserve untargeted content. Zero whole-file overwrites. Idempotent.
+- Self-healing vs halt [CRITICAL]: compile/type error → read diagnostic → ONE autonomous fix → recompile.
+- Pre-response self-audit: before completion, verify: [ ] LOC density tiers respected (≤150/≤300, 300–500 state machines only, hard ceiling 500)? [ ] `../` traversals eliminated? [ ] delta-merging used? [ ] local compiler/linter ran? [ ] `git submodule status` no `+`/`-`? [ ] `./scripts/check.sh` ran and exited 0 (open `check` skill for gate diagnostics)? Any fail → correct autonomously before reply. Then report `[Implementing]` → `[Paused/Blocked]` → `[Completed: Added X, Modified Y, Removed Z]`.
+
+## 11. Observability, Evolution & Debug-by-Default
+
+- Telemetry: flat OTLP JSONL log-record (NOT resourceLogs wrapper): `timeUnixNano`, `severityNumber` (TRACE=1 DEBUG=5 INFO=9 WARN=13 ERROR=17 FATAL=21), `severityText`, `body`, `attributes` (incl. `service.name`), `traceId`/`spanId`. Propagate `request_id`. Mask PII/PHI (GDPR strict).
+
+```json
+{"timeUnixNano":"1723723200000000000","severityNumber":5,"severityText":"DEBUG","body":"market catalog fetched","attributes":{"service.name":"market-scan","offers":2346},"traceId":"4bf92f3577b34da6a3ce929d0e0e4736"}
+```
+
+- Produced code verbose-by-default: `VERBOSE=0|false` → WARN/13 only; `VERBOSE=1|true` or MISSING → everything (TRACE/1). `LOGS=0|false` → no file sink; `LOGS=1|true` or MISSING → mirror to per-module `<module>.log`. Console always mirrors (gated by VERBOSE). REDACTION NOT GATED BY VERBOSE: token/vid/otp/jwt/key/secret redacted at emission, every setting. Existing modules keep `LOG_LEVEL`; new uses `VERBOSE`/`LOGS`.
+- Testing & docs: DI → deterministic QA. Comment *why*. ADRs as OKF concepts.
+- Test design matrix (two-layer, proactive): Layer 1 systematic coverage — cover every exclusion/branch, empty/null, bounds/cap, permission gate in spec scenarios (spec IS checklist). Layer 2 autonomous adversarial — invent one fixture breaking happy-path (real-world order not sorted, type-coerced inputs, stale ids, empty vs populated). Fixture rule: never only sorted/happy-path for ordering-sensitive code.
+- API/Evolution: strict schemas (OpenAPI/gRPC), SemVer, graceful deprecation.
+- Refactoring: Boy Scout Rule → incremental debt resolution.
+- Green Ops/2026 SOTA: minimize carbon. Cross-reference 2026 SOTA → prevent hallucination.
+
+## 12. Version Control, Releases & Scaffolding
+
+- Module scaffolding [CRITICAL]: new app module → `git init` inside `./<project>-<module>/` → remote → `git submodule add` to parent orchestrator + `mkdir -p .github/workflows` with per-module `quality.yml` (native lint/test/build lane; standalone microservices add `deploy.yml`); orchestrator owns unified `deploy.yml` (multi-stage `Dockerfile → musl → distroless` + `SUBMODULE_TOKEN` + `paths:` allowlist).
+- Orchestrator deploy pipeline [CRITICAL]: `deploy.yml` watches deployable submodule dirs + `Dockerfile` + `deploy.yml` via `paths:`. Uses `secrets.SUBMODULE_TOKEN` for both checkout and GHCR login (`write:packages`). Dokku deployment step uses `appleboy/ssh-action` with explicit `port: ${{ secrets.DOKKU_SSH_PORT }}` and triggers `dokku git:from-image <project> ghcr.io/<owner>/<project>:<version>`.
+- `.gitignore`: secure default-deny (block `*`, allowlist source) in root AND EACH submodule. Update actively → prevent credential leaks.
+- SemVer: strict `MAJOR.MINOR.PATCH` per module.
+- Changelog: `./<project>-<module>/CHANGELOG.md` (`## VERSION - YYYY-MM-DD`). Categories `Added`/`Changed`/`Removed`/`Fixed`. Imperative mood.
+- Push gate [CRITICAL] — two lanes, per touched submodule (generic; host caches `swatinem/rust-cache` / `oven-sh/setup-bun` + multi-arch `ubuntu-26.04` + `ubuntu-26.04-arm` matrix `cache-from/to: type=gha` NEVER QEMU; stack mappings: Bun `bun run check && bun test && bun run build`, Rust `cargo fmt --check && cargo clippy -- -D warnings && cargo test && cargo build --release`):
+  - **Blocking (exit 1):** per touched submodule run native codegen (if exists) → lint → tests → hermetic/static build in builder image → secret-leak scan (new dirs/`*.env` patterns, `git submodule status | grep "^-"`) → submodule-pointer freshness (`git submodule status | grep "^\+"`). Any failure → `exit 1` with failing command. No project names in rule body. Fails pre-push ~15s, not remote. **Advisory (exit 0):** `sem diff --format json` + manifest version + `CHANGELOG.md` presence. Inform, never block.
+- Check script maintenance [CRITICAL]: Workspace orchestrator root and each submodule MUST maintain an executable `./scripts/check.sh` implementing the canonical 6-slot contract (Pointers, Secrets, Native Lanes, Tracked Assets, Clean-Clone Sandbox, Smoke) and supporting `--quick` (sub-10s iteration exiting before sandbox). Root orchestrator checks submodule freshness/credentials and delegates to submodule check scripts; submodules verify native format/lint/test lanes, assert compile-time asset tracking (`git ls-files --error-unmatch`), honor `--quick`, and verify committed buildability via hermetic clean clone (`mktemp -d` + `git clone .`). Agents MUST update check scripts whenever manifests, dependencies, or compile-time assets change. Consult `check` skill for anatomy and diagnostic procedures.
+
+## 13. Guide Maintenance
+
+- Rule file: edit like refactor — preserve meaning unless explicitly scoped, one change at a time.
+- Verify with cold-agent test: reads section once, obeys without questions.
+- Rules cost per-read tokens: keep only what pays rent (net value, measured with tokenizer).

package/CHANGELOG.md

@@ -0,0 +1,236 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [5.0.2] - 2026-09-23
+
+### Changed
+
+- **Refined LOC density tiers in `AGENTS.md`** (`refine-agents-loc-tiers`): replaced flat binary >500 LOC rule with an explicit 4-tier code density model across Must-follow rules (L19), Core Engineering Pillars §2 (L68), and Pre-response self-audit §10 (L202):
+  - Tier 1 (≤150 LOC): Atomic/leaf target for near-zero hallucination, minimal token burn, and flawless diff patches
+  - Tier 2 (≤300 LOC): Cohesive domain sweet spot balancing context, complete signatures, and reliable multi-turn edits
+  - Tier 3 (300–500 LOC): Upper boundary exception strictly confined to complex state machines, protocol parsers, and unified event reducers, with explicit acknowledgment of increased latency and token burn
+  - Tier 4 (>500 LOC): Hard ceiling failure-prone threshold; touched files require completing immediate objective, then flagging ADR-tracked decomposition
+
+## [5.0.1] - 2026-09-22
+
+### Changed
+
+- **Multi-arch runner matrix upgraded to Ubuntu 26.04** (`upgrade-runner-matrix-ubuntu-26`): explicitly pin GitHub Actions parallel native multi-arch runners to `ubuntu-26.04` (amd64) and `ubuntu-26.04-arm` (arm64) across `project/AGENTS.md` and `pipeline-multiarch-caching` spec, eliminating OS skew and preparing ahead of the `ubuntu-latest` alias migration
+
+## [5.0.0] - 2026-09-22
+
+### Added
+
+- **In-Browser Entity Simulation Layer (Miniplex ECS)** (`refine-canonical-stack-architecture`): formalize `miniplex` (with `miniplex-svelte`) as universal client-side ECS for dynamic polymorphic entity lifecycles and zero-allocation frame-by-frame archetype queries (`world.with(...)`), decoupled from downstream presentation adapters
+- **Babylon.js 3D engine support**: formalize `babylonjs` alongside Threlte for industrial WebGPU compute, node materials, and native Havok physics simulations
+- **Tauri v2 native shell**: adopt Tauri v2 as the cross-platform native shell packaging the existing SvelteKit static SPA build for Desktop (macOS, Windows, Linux) and Mobile (iOS, Android) via Rust IPC
+- **Candle in-process ML**: embed Hugging Face's `candle` into Tier 4 alongside Tokio and Rayon for zero-Python, in-process GGUF/Safetensors vector embeddings and local LLM/SLM inference
+
+### Changed
+
+- **Canonical 5-tier architecture aligned**: formalize 5 discrete tiers (Tier 1: Web & Native UI Shell via SvelteKit + Tauri v2, Tier 2: In-Browser Entity Simulation via Miniplex ECS, Tier 3: In-Browser Presentation Matrix via Threlte/Babylon.js/PixiJS/Phaser, Tier 4: Compute & Systems via Rust Axum+Tokio+Rayon+Candle, Tier 5: Event-Driven Transport & Distroless Hardening)
+- **Threlte nomenclature cleaned**: rename "Threlte+Three.js" to simply "Threlte" across directives, specifications, and Context7 triggers
+- Context7 framework intelligence triggers updated to include `miniplex`, `babylonjs`, `tauri`, and `candle`
+
+### Removed
+
+- **BREAKING: Bevy game engine purged**: completely remove Bevy from compute tier, specifications, and topological sort to eliminate heavy C-library dependencies (ALSA, udev, Vulkan) and speculative WASM bloat; compute tier standardizes on pure Tokio + Rayon + Candle
+- **Capacitor removed**: purge Capacitor in favor of Tauri v2 native desktop and mobile shell
+
+## [4.2.0] - 2026-09-21
+
+### Added
+
+- **design-craft skill** (`design-craft`): ninth shipped skill — a project- and language-agnostic design syllabus with four modes (Build, Review, Polish, Motion); a thin agnostic body (8 modules, ~1350 tokens) plus six attributed Tier-3 references (`art-direction`, `design-engineering`, `motion-craft`, `anti-slop-patterns` with 24 named patterns, `review-checklist`, `process`); 7 evals / 20 assertions covering two positive routes, two anti-triggers (backend work, renderer choice), anti-slop refusal, bounded verification, and agnosticism; behavioral gate recorded `d = +1, m = 0.35`
+- **Vendored Web Interface Guidelines digest** inside `design-craft/references/review-checklist.md`: MIT, captured 2026-09-21, so a review completes with no network access while the live fetch stays available as a refresh path
+
+### Changed
+
+- Total shipped skills increased from 8 to 9
+- **`skill-lifecycle-governance` capability amended**: the hard cap of 8 became an advisory ceiling — `prune` and `merge` proposals remain available on their own evidence but are no longer forced at the boundary (owner decision to ignore the cap)
+
+## [4.1.1] - 2026-09-17
+
+### Fixed
+
+- **Completed `skill-creator` → `create-skill` rename** (`finish-skill-creator-rename`): repointed CI validator invocations in `project/.github/workflows/quality.yml` to `skills/create-skill/scripts/` (previously invoked scripts from the deleted path on every run); renamed skill-name references in `openspec-learn` SKILL.md plus references; fixed README skill-table row plus loop diagram; synced 7 main specs (`skill-creation`, `learn-proposal-contract`, `learn-compound-gains`, `behavioral-proof-flywheel`, `tooling-contract-alignment`, `agent-compound-directive`, `artifact-integrity`)
+
+## [4.1.0] - 2026-09-17
+
+### Added
+
+- **check skill** (`add-check-skill`): pre-push and workspace integrity gate execution manual — instructs agents to observe the two-speed verification protocol (`--quick` vs full pre-flight), enforce the canonical 6-slot contract (submodule pointers, credential scans, native lanes, tracked compile-time assets, hermetic clean-clone sandbox, smoke tests), and apply self-healing recipes from `references/diagnostic-matrix.md` (109 lines)
+- **check-deps utility** (`project/scripts/check-deps.mjs`): lightweight, download-free dependency freshness verifier across Rust/Cargo, Bun/NPM, and active system toolchains with flexible target directory scanning
+- **git-dl utility** (`project/scripts/git-dl.mjs`): fast archive downloader streaming release tarballs from GitHub's codeload endpoint into `./references/<repo>` with automatic directory creation
+- **project scripts distribution**: `project/install.ts` now diff-synchronizes `project/scripts/*` into `<targetDir>/scripts/` with executable permissions (`0o755`), tracking scripts in `.agentic-manifest.json`
+- **package scripts and binaries**: `project/package.json` now exposes `check-deps` and `git-dl` in both `"scripts"` and `"bin"`
+
+### Changed
+
+- Total shipped skills increased from 7 to 8 with the addition of `check`
+- `project/AGENTS.md`: §12 mandates executable `./scripts/check.sh` maintenance in workspace orchestrator and submodules; §10 Pre-response self-audit requires exit 0 check gates before task completion; §8 registers `check` skill
+
+## [4.0.0] - 2026-09-02
+
+### Added
+
+- **guardrails skill** (`agentic-perfection-flywheel`): first-loaded cross-cutting hardening — `Contrast` table + 5 `Anti-examples` (`on*` stripping, secret leak, `adapter-static`, `Option` vs `null`, lifetime elision) harvested from `openspec/reports/*` clustering; `references/guardrails-patterns.md` Level 2 (700 tokens); `project/AGENTS.md` adds `Must-read: project/skills/guardrails/SKILL.md before any code touching deps/Docker/HTML/auth` (223 lines)
+- **Behavioral proof flywheel** (`agentic-perfection-flywheel`): `project/skills/skill-creator/scripts/run-cold-eval.mjs` — cold A/B harness running `evals/evals.json` without vs with skill, computes `d = sign(with - baseline)`, `m = |with - baseline|`, emits unified envelope + `behavioral: {at, baseline, with_skill, d, m, ship}` (30s timeout, JSON only); `skill-creator` Phase 5/7 now fail-closed `d == +1 and m >= 0.2` (was structural-only)
+- **Compound dashboard** (`agentic-perfection-flywheel`): `openspec/reports/dashboard.md` generated by `openspec-learn` Phase 2f — table `keyword | count | avg Time Cost | avg Re-use | owning skill | m` sorted by `frequency × cost` desc, cited as `Source: dashboard.md#keyword` in proposals
+- **Skill lifecycle governance** (`agentic-perfection-flywheel`): `openspec-learn` now proposes `prune` (0/10 or `m < 0.2`), `merge` (≥3 shared gaps), `split` (needs `and`); cap 8 — at cap `create` must pair with `prune`/`merge`, all with `Deferred:`
+- **Teaching-optimized loop** (`upgrade-learning-loop-for-compound-gains`): `openspec-report` adds `Mental Model Shift` (Before→After) + `Surprise vs Expectation` + `Concrete Gotcha` (before/after+Signal) + `Time Cost` + `Re-use Score` to `report.md.template`/`assessment.md.template` and SKILL.md; `openspec-learn` adds clustering `frequency × cost` + `Contrast:`/`Anti-example:` hints + layer-aware `1/2/3`; `skill-creator` adds `Contrast` table + `Anti-examples` as first-class body content distinct from `anti_triggers` + `Tiered depth` (Level 1 inline, Level 2 `references/<topic>.md`, cap one file)
+- **AGENTS.md compound nudge** (`upgrade-learning-loop-for-compound-gains`): `After tasks with difficulty ≥3/5, surprise, or time cost >30m → suggest Want /opsx-report? (never auto-run)` + boundary `Learned negatives live in skills — human-owned only`
+
+### Changed
+
+- **skill-creator leanness** (`agentic-perfection-flywheel`): 362→290 lines — `Fragility Matching` + `Component Decomposition` moved to `references/` Level 2 with explicit links; `assets/templates/SKILL.md.template` adds `References` with `See ../../guardrails/SKILL.md` deduplication
+- `project/AGENTS.md` 220→223 lines — retains general OS core, adds guardrails pointer + compound nudge
+- `project/install.ts` — remove dead `promptsSrc` handling (`project/prompts/` deleted 2026-09-01), manifest now `prompts: []` hard-coded
+
+### Removed
+
+- **BREAKING: `source-fetcher` skill** — `project/skills/source-fetcher/` (SKILL.md + 4 scripts `detect-stack/scan-deps/download-src/cleanup-src` + 3 references + evals) removed from distribution; consumers needing `references/src/` should vendor separately; `install.ts` dynamic `readdirSync` now ships 6 skills (was 7 with guardrails, now 6 after removal)
+
+## [3.0.0] - 2026-08-28
+
+### Changed
+
+- **BREAKING**: Stack migration `rust-axum-svelte-sqlx-tsrs` — `svelte-adapter-bun` → `@sveltejs/adapter-static` (`fallback: 'index.html'`) with `tower-http` ServeDir/ServeFile; Axum/Tokio becomes sole coordinator (migrations in `crates/api/migrations/` via `sqlx migrate`, pool via `sqlx`); `ts-rs` `#[ts(export)]` via `cargo test` to `frontend/src/lib/types/bindings/` (gitignored) with `sqlx-data.json` hermetic CI; single multi-stage build `Vite → Rust musl → gcr.io/distroless/static-debian13:nonroot` (eliminate `oven/bun:distroless` from prod); `vite dev` proxies `/api`+`/ws` to `cargo watch -x run` with route-precedence guard
+- `project/AGENTS.md` §4/§6/§10, `prototype/AGENTS.proto.md` aligned to canonical Axum+SQLx+ts-rs 5-tier; Drizzle (`drizzle-orm`/`drizzle-kit`) removed from web tier; tags `drizzle`+`svelte-adapter-bun`+`bun` → `adapter-static`+`sqlx`+`ts-rs`
+
+### Added
+
+- `ts-rs-bindings` capability — TS generation + offline `sqlx-data.json` via `cargo sqlx prepare`
+- `tonic`/`Protobuf` gRPC for backend inter-module worker communication
+
+### Fixed
+
+- Container hardening collapsed to single distroless runtime
+
+## [2.4.0] - 2026-08-27
+
+### Added
+
+- **openspec-harden skill + `opsx-harden` prompt** (`add-proposal-improve-bridge`): harden any existing change for cold application — enriches proposal/specs/design/tasks with concrete file paths, code blocks, verify steps, and grounded codebase context (ripgrep + Read); enforces cold-readiness checklist, append-only intent preservation, store-aware handling, planning-only boundary, and idempotent re-run
+
+### Changed
+
+- **BREAKING (skill names):** `opsx-learn` → `openspec-learn`, `opsx-report` → `openspec-report` (skill directories + `name:` frontmatter); prompt files keep `opsx-*` names for muscle memory but now load `openspec-*` skills with unified `**Store handling:**` + `**Remaining args:** ${@}` footer (8 lines)
+- `openspec-harden` skill: `openspec-proposal-improve` → `openspec-harden` and `opsx-improve.md` → `opsx-harden.md`; prompt/skill now share `harden` terminology
+- `openspec-harden` guardrail: `Read-only commands and file reads need no confirmation` (mirrors upstream explore `1.11.0` clarification)
+
+### Fixed
+
+- `okf-docs` example actor `opsx-report/1.0` → `openspec-report/1.0` for naming consistency
+
+## [2.3.0] - 2026-08-24
+
+### Added
+
+- **okf-docs skill** (`revive-okf-docs-skill`): revived as 5th distributed skill — author OKF v0.2-compliant documents (ADRs, module docs, decision records) with mandatory provenance frontmatter (`type`, `generated.by/at`, `sources`, `status` lifecycle) and mechanical validation via bundled `validate-frontmatter.mjs` (unified envelope, checks type/generated, actor convention, status enum, stale_after chronology); ships with 3 evals incl. anti-trigger vs opsx-report/opsx-learn
+- Canonical stack alignment in `project/AGENTS.md`: verbatim 5-tier high-efficiency architecture (General & UI Tier SvelteKit via svelte-adapter-bun/Drizzle/PostgreSQL, In-Browser Graphics Threlte+Three.js/PixiJS/Phaser, Compute Rust Axum+Rayon/Bevy, Event-Driven PostgreSQL LISTEN/NOTIFY with WSS/SSE, Container Hardening distroless) plus Modular Extensibility bridge — `System components communicate via strict interface contracts and stateless micro-modules, supporting runtime plugin loading and independent horizontal scaling`
+- `prototype/AGENTS.md` v2 scalable extensibility core (agnostic) — orchestrator-workers, durable state machine, stateless workers, backpressure, event-driven WSS/SSE, futureproof-by-construction pillar
+
+### Changed
+
+- `project/AGENTS.md` optimized to 215 lines (from 223) — semantic caveman density, hierarchy repaired (Summary + Must-follow flat list), boundaries consolidated; stack opinions preserved, purged legacy Go/Datastar/templ mentions (Mental Model table genericized, `Layer 1 systematic coverage`)
+- READMEs now list 5 skills (added okf-docs) and `bunx github:meyverick/agentic` provenance manifest
+
+### Fixed
+
+- Validator JSON envelope unification — `validate-routing.mjs`, `validate-structure.mjs`, `audit-antipatterns.mjs` now share `{target, pass, checks:[{id,status,detail}], summary}` for deterministic branching (previously 3 dialects)
+- `project/AGENTS.md` frontmatter cleaned to production (stable, self-contained, portable — removed workshop `draft` metadata referencing `prototype/`)
+- `project/AGENTS.md` §8 path alignment: `.agents/skills/` → `.pi/skills/` (matches installer target)
+- `.qmd/index.sqlite` now gitignored and untracked (was perpetual `M` noise)
+
+## [2.2.0] - 2026-08-23
+
+### Added
+
+- **Ownership boundary** (`harden-learn-proposal-contract`): opsx-learn Phase 2c classifies skill/prompt targets via precedence chain — provenance manifest (`.agentic-manifest.json`), user adjudications (`.ownership.json`), location and namespace checks; external skills (OpenSpec-owned, agentic-distributed elsewhere, user-global) are never edited in place; unknown → ask user once, record verdict
+- Installer writes `.pi/skills/.agentic-manifest.json` (installed_by, version, skills, prompts) and warns before atomic-replace when local modifications are detected; `.ownership.json` never touched by installer
+- Canonical trigger field names in proposals (`positive_triggers`/`anti_triggers`) — values transfer verbatim into skill frontmatter
+- One-path rule: proposal items and task verify clauses name exactly one concrete target path; either/or prohibited
+- Evals-impact statement mandatory when proposals modify existing skills
+- Deferred-signals line: unharvested report candidates named with reasons
+- Timestamp rule in opsx-report: `date -u` generated, never hand-written
+- Two-stage benchmarks: structural `benchmark.json` for all 4 skills (validator + routing + eval metrics); behavioral d×m defined as `pending_cold_agent_run`
+- Script reachability: source-fetcher phases invoke their 4 bundled scripts (detect-stack, scan-deps, download-src, cleanup-src)
+
+### Changed
+
+- Root and project READMEs rewritten to reflect the actual 4-skill product and `bunx github:meyverick/agentic` installation
+
+### Removed
+
+- opsx-learn `scripts/` directory (analyze-report.mjs duplicated Phase 2 prose; compare-skills.mjs + measure-quality.mjs duplicated skill-creator's validate pair / compute-benchmark)
+- opsx-learn stale `runtime:` frontmatter block (skill emits markdown proposals, not JSON; instruction-only skills carry no runtime contract)
+
+### Fixed
+
+- Duplicate `syncFile` definition in install.ts removed
+- False `output_format: json` claim on opsx-report removed (2.1.0 follow-through)
+
+## [2.1.0] - 2026-08-22
+
+### Added
+
+- Eval suites for `opsx-report` (3 evals: trigger routing, anti-trigger vs opsx-learn boundary, archive-reference behavior) and `source-fetcher` (3 evals: recursive scan, cleanup idempotence, sources.json override precedence)
+- skill-creator validator hard gate: Phase 7 Ship blocks approval unless validate-structure.mjs AND validate-routing.mjs pass with recorded evidence
+- Evidence-recording requirement in skill-creator Phase 4 (validator output captured in session artifacts)
+- Author Self-Check section in SKILL.md.template — gate awareness survives into generated skills
+- Gate-compliance eval (id 4): cold-agent creation must execute both validators and record passes before completion claim
+- Main specs seeded: `skill-quality-enforcement`, `skill-creation`
+
+### Fixed
+
+- opsx-report false runtime contract removed (`output_format: json` claimed but skill emits markdown; instruction-only skill needs no runtime block)
+
+## [2.0.0] - 2026-08-20
+
+### Added
+
+- **BREAKING**: Integrated workflow — reports now generated at `./openspec/reports/` instead of external `./reports/`
+- `opsx-report` skill: self-reflection (meditation) on archived changes with assessment
+- `source-fetcher` skill: project-agnostic dependency source download to `./references/src/` with sources.json cache and cleanup mode
+- `validate-routing.mjs`: semantic routing validation (positive_triggers, anti_triggers, description-body alignment, single-responsibility)
+- Research-informed quality standards: positive_triggers (min 3), anti_triggers (min 2), activation boundaries, runtime contracts, output contracts, portability checks, context budget validation, quality score (d × m)
+- Thin prompt architecture: prompts reduced to ~8-line entry points that invoke skills
+- Atomic skill replacement in install script (replace entire skill if ANY file differs)
+- Recursive dependency scanning in source-fetcher (depth limit 5, skips node_modules/target/dist)
+- Antipatterns A17-A20 added to audit script
+
+### Changed
+
+- `opsx-learn` renamed from `skill-auditor`, relocated to `project/skills/`
+- `skill-creator` relocated from `.pi/skills/` to `project/skills/`, upgraded to v2.0 with research-informed standards
+- All scripts converted from `.sh` to `.mjs` (ES modules, self-contained, JSON output)
+- Prompts use integrated argument syntax (e.g., `${@:-latest}`) instead of separate "Provided arguments" line
+- Reports are self-reflection (meditation), not copies of archives — they reference archive paths instead
+
+### Removed
+
+- `./reports/` workflow (replaced by `./openspec/reports/`)
+- `changelogs/` directory (replaced by per-module CHANGELOG.md)
+- `.pi/prompts/skill-create.md` and `.pi/prompts/skill-improve.md` (replaced by opsx-learn combo)
+- Wiki directories from individual skills
+
+### Fixed
+
+- Multi-line YAML description parsing in validate-structure.mjs
+- Bun lockfile detection (`bun.lock` in addition to `bun.lockb`)
+- Recursive dependency scanning in source-fetcher scan-deps.mjs
+- Actual source download via git clone (was placeholder README)
+
+## [1.0.0] - 2026-08-19
+
+### Added
+
+- Initial release of agentic skills for pi.dev
+- skill-creator and skill-auditor skills
+- opsx-report prompt
+- install.ts via bunx

package/README.md

@@ -0,0 +1,50 @@
+# Agentic
+
+Self-improving AI agent skills and prompts for [pi.dev](https://pi.dev). A closed-loop factory: analyze reports → generate proposals → apply improvements → reflect.
+
+## Install
+
+```bash
+bunx @meyverick/agentic
+```
+
+*(or via GitHub direct: `bunx github:meyverick/agentic`)*
+
+Installs 9 skills into your project's `.agents/skills/`, distributes utility scripts into `./scripts/`, writes a provenance manifest, and creates `openspec/reports/`.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| check | Pre-push and workspace integrity gate execution — executes two-speed check scripts, diagnoses failures, and applies self-healing recipes |
+| create-skill | Create new agent skills end-to-end: discovery, design, authoring, validation gates, behavioral proof, evals, shipping |
+| design-craft | Craft intentional interface design on any stack — art direction, review, polish, and motion, agnostic of framework |
+| guardrails | Cross-cutting hardening for security, deprecated APIs, and system gotchas — loads first before domain skills |
+| okf-docs | Author OKF v0.2-compliant documents — ADRs, module docs, decision records — with mandatory provenance frontmatter and mechanical validation |
+| openspec-harden | Harden an existing OpenSpec change for cold application — enrich artifacts with concrete file paths, code blocks, and verify steps |
+| openspec-learn | Analyze reports in `./openspec/reports/` and generate OpenSpec proposals for skill/prompt improvements |
+| openspec-report | Generate self-reflection (meditation) reports from archived OpenSpec changes |
+| qmd-research | Research project markdown and specifications using local QMD hybrid search, and maintain index collections |
+
+## The Loop
+
+```
+archived change → /openspec-report → report + assessment
+                                      ↓
+                              /openspec-learn → proposal
+                                      ↓
+                             /openspec-harden → cold-ready artifacts
+                                      ↓
+                              /openspec-apply → create-skill builds it
+                                      ↓
+                             /openspec-archive → main specs updated
+```
+
+Each cycle makes the skill set better at improving itself.
+
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.0
+- [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec) (for the openspec-* loop)
+- pi.dev-compatible agent harness (skills install to `.agents/skills/`)
+- [qmd](https://www.npmjs.com/package/@tobilu/qmd) (optional — the loop falls back to `grep` when absent)