@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/smidja/smidja_simple_sdlc.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Simple SDLC — plan, build, test, review, document, committing as it goes.
+
+Usage:
+    uv run smidja/smidja_simple_sdlc.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> planner -> git(commit_plan)
+        -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded]
+        -> reviewer [-> builder(revise) -> reviewer ... bounded]
+        -> code(retest, only if a revision changed code)
+        -> git(commit_build) -> code(changes) -> documenter -> git(commit_docs)
+
+Three commits, three work products, three authors. The plan, the code, and the
+write-up each land in their own commit, and each commit message is the words of
+the agent that produced it — `commit_message` on PlanOutput describes the spec,
+on BuildOutput the code, on DocumentOutput the write-up. No agent's sentence is
+ever reused for another agent's diff.
+
+Testing is CODE, not an agent. `bun test` is a command, not a judgement call:
+an agent rediscovering it every run costs a million tokens to learn what a
+subprocess already knows. Failures travel back to the builder as an envelope,
+so the repair loop is unchanged — only the runner became free and repeatable.
+
+Two different questions still get asked, in order. The suite asks "does it
+run"; the reviewer asks "is this what was asked for", against `plan.md` — and
+neither can answer the other's. A revision that closes a review finding
+re-enters the suite, so the tree that gets committed is the tree that was both
+tested and approved.
+
+The code commit lands after verification, not straight after the build: fixes
+and revisions are part of the same work product, and red code has no business
+on the branch. A run that fails verification therefore leaves the plan
+committed and the working tree dirty — the spec is a real artifact either way,
+and the unfinished code stays where the engineer can see it.
+
+The documenter measures against the commit this run STARTED from, not against
+`main`, because by then the run has moved `main` itself. That baseline is
+pinned before the first commit phase and printed in the request phase.
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, changes, gates, git_helper, quality, session, utils
+from smidja_modules.data_types import (AgentCall, BuildOutput, ChangeCapture,
+                                    DocumentOutput, PhaseParams, PlanOutput,
+                                    ReviewOutput)
+
+REQUIRED_AGENTS = ["planner", "builder", "reviewer", "documenter"]
+MAX_FIX_LOOPS = 3
+MAX_REVISION_LOOPS = 2
+
+DOCUMENT_NOTES = ("Read diff_path in full before writing. Document only what the "
+                  "diff shows, then copy the write-up into app_docs/ as your task "
+                  "describes.")
+
+
+def main(prompt: str, config: str = "smidja/smidja_smidja_config/smidja.config.yaml", smidja_id: str | None = None) -> int:
+    cfg = agents.load_config(config)
+    agents.validate(cfg, REQUIRED_AGENTS)
+    run = session.ensure(cfg, smidja_id)
+    baseline = git_helper.rev("HEAD")     # pinned before this run commits anything
+
+    def commit(ph, envelope) -> None:
+        """Commit what the preceding phase produced, in that agent's own words."""
+        message = envelope.commit_message or f"smidja({run.smidja_id}): {envelope.summary}"
+        ph.log(sha=git_helper.commit_all(message), message=message)
+
+    def record(ph, result) -> None:
+        """Log a deterministic block's verdict — the same shape every smidja uses."""
+        passed = sum(1 for check in result.checks if check.passed)
+        ph.log(passed=result.passed, checks=f"{passed}/{len(result.checks)}",
+               artifacts=", ".join(result.artifacts))
+
+    with run.phase(PhaseParams(name="request", kind="engineer", owner=run.engineer,
+                               description="Capture the incoming ask")) as ph:
+        ph.log(input=prompt, baseline=git_helper.short_sha(baseline))
+
+    with run.phase(PhaseParams(name="plan", kind="agent", owner="planner",
+                               description="Turn the request into an implementable plan")) as ph:
+        plan = ph.call(AgentCall(output_type=PlanOutput, prompt=prompt,
+                                 gates=[gates.artifacts_exist, gates.files_non_empty]))
+
+    with run.phase(PhaseParams(name="commit_plan", kind="code", owner="git",
+                               description="Put the spec on record before any code exists to blur it")) as ph:
+        commit(ph, plan)
+
+    with run.phase(PhaseParams(name="build", kind="agent", owner="builder",
+                               description="Implement the plan exactly")) as ph:
+        build = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt, previous=plan,
+                                  gates=[gates.diff_matches_claims]))
+
+    test = None
+    for i in range(1, MAX_FIX_LOOPS + 1):
+        with run.phase(PhaseParams(name=f"test_{i}", kind="code", owner="quality",
+                                   description="Run the suite — a known command, so code runs "
+                                               "it and no agent has to rediscover it")) as ph:
+            test = quality.run_tests(run)
+            record(ph, test)
+
+        if test.passed:
+            break
+
+        with run.phase(PhaseParams(name=f"fix_{i}", kind="agent", owner="builder", retries=1,
+                                   description="Repair what the suite reported, from its "
+                                               "verbatim output")) as ph:
+            build = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt,
+                                      previous=quality.as_envelope(test, "tests"),
+                                      gates=[gates.diff_matches_claims]))
+
+    review = None
+    revised = False
+    for i in range(1, MAX_REVISION_LOOPS + 1):
+        with run.phase(PhaseParams(name=f"review_{i}", kind="agent", owner="reviewer",
+                                   description="Confirm the build matches the plan")) as ph:
+            review = ph.call(AgentCall(output_type=ReviewOutput, prompt=prompt, previous=build,
+                                       gates=[gates.artifacts_exist, gates.verdict_consistent]))
+
+        if review.approved or i == MAX_REVISION_LOOPS:
+            break
+
+        with run.phase(PhaseParams(name=f"revise_{i}", kind="agent", owner="builder", retries=1,
+                                   description="Close the reviewer's blocking findings")) as ph:
+            build = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt, previous=review,
+                                      gates=[gates.diff_matches_claims]))
+            revised = True
+
+    # A revision edited code after the suite last ran, so the green light is
+    # stale. Re-run it rather than commit on a result that predates the change.
+    if revised and review is not None and review.approved:
+        with run.phase(PhaseParams(name="retest", kind="code", owner="quality",
+                                   description="Re-run the suite — the revision changed code "
+                                               "after the last green result")) as ph:
+            test = quality.run_tests(run)
+            record(ph, test)
+
+    # Red tests or a rejected review stop the chain here: the code stays
+    # uncommitted and nothing is documented, because there is nothing worth
+    # describing yet. The plan commit stands — it is a record of what was asked.
+    verified = (test is not None and test.passed
+                and review is not None and review.approved)
+    if verified:
+        with run.phase(PhaseParams(name="commit_build", kind="code", owner="git",
+                                   description="Land the code only now: green suite, approved review")) as ph:
+            commit(ph, build)
+
+        with run.phase(PhaseParams(name="changes", kind="code", owner="git",
+                                   description="Diff the whole run against its pinned baseline, for the documenter")) as ph:
+            changeset = changes.capture(run, ChangeCapture(base=baseline))
+            ph.log(base=f"{changeset.base.label} @ {changeset.base.commit[:7]}",
+                   reason=changeset.base.reason,
+                   files=len(changeset.files) + len(changeset.untracked),
+                   lines=f"+{changeset.insertions} -{changeset.deletions}",
+                   diff=changeset.diff_path)
+            if changeset.empty:
+                raise RuntimeError(
+                    f"nothing changed since {changeset.base.label} "
+                    f"({changeset.base.reason}) — there is nothing to document.")
+
+        with run.phase(PhaseParams(name="document", kind="agent", owner="documenter", retries=1,
+                                   description="Write up the completed change")) as ph:
+            document = ph.call(AgentCall(output_type=DocumentOutput, prompt=prompt,
+                                         previous=changes.as_envelope(changeset, DOCUMENT_NOTES),
+                                         gates=[gates.artifacts_exist, gates.files_non_empty]))
+
+        with run.phase(PhaseParams(name="commit_docs", kind="code", owner="git",
+                                   description="Ship the write-up in its own commit, beside the code it describes")) as ph:
+            commit(ph, document)
+
+    return run.finish(accepted=verified,
+                      reason="the suite or the review never came back clean")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("prompt", help="inline text or a path to a prompt file")
+    parser.add_argument("--config", default="smidja/smidja_smidja_config/smidja.config.yaml")
+    parser.add_argument("--smidja-id", default=None, help="join or pin an existing session")
+    args = parser.parse_args()
+    sys.exit(main(utils.resolve_prompt(args.prompt), args.config, args.smidja_id))

package/apps/smidja/smidja_smidja_config/smidja.config.yaml

@@ -0,0 +1,143 @@
+# smidja.config.yaml — the smidja's agent roster. One agent, one prompt, one purpose.
+# v1 runs the Pi coding agent only; coding_agent: claude_code arrives in v2.
+defaults:
+  coding_agent: pi
+  model: ${SMIDJA_LOCAL_MODEL:-llama-cpp/qwen3.6-35b-a3b@iq3_s}   # provider/id from pi models.json; override with SMIDJA_LOCAL_MODEL
+  thinking: medium                 # off | minimal | low | medium | high | xhigh | max
+  harness_engineering: []          # pi extensions loaded into the harness (-e)
+  # Roster-wide allowlist; any agent may override with its own list.
+  # NOTE: --tools filters extension and custom tools too, not just builtins. An agent
+  # whose harness_engineering extension registers a tool MUST name that tool in its own
+  # tools list — otherwise the extension loads and its tool is silently filtered out.
+  tools:
+    - read                         # read file contents
+    - bash                         # execute bash commands
+    - edit                         # find/replace edits
+    - write                        # create/overwrite files
+    - grep                         # search file contents  (pi default: OFF)
+    - find                         # find files by glob     (pi default: OFF)
+    - ls                           # list directories       (pi default: OFF)
+  # Off-limits to every agent that does not name them in its own `writes`.
+  # `tools` alone cannot protect these: bash runs `git checkout`, and write
+  # reaches any path. An agent must not be able to edit the machinery that
+  # decides whether its own work passed. Enforced in smidja_modules/permissions.py.
+  #
+  # `writes:` per agent says what it may change IN THE REPO. It never restricts
+  # the session runtime under data_dir — context_handoff/, envelopes, prompts,
+  # raw output. Every agent can always write its own report; `writes: []` means
+  # read-only with respect to the repo, not mute.
+  protected_files:
+    - apps/smidja/smidja_modules/
+    - apps/smidja/smidja_smidja_config/
+    - apps/smidja/smidja_*.py
+  data_dir: apps/smidja/smidja_data          # runtime home: {data_dir}/sessions/{smidja_id}/{agent_name}/
+
+observability:
+  db: apps/smidja/smidja_data/smidja.db        # tracer writes here directly; the UI polls it
+  poll_ms: 500                     # visualizer live-poll cadence
+
+agents:
+  - name: planner
+    model: ${SMIDJA_PLANNER_MODEL:-${SMIDJA_LOCAL_MODEL:-llama-cpp/qwen3.6-35b-a3b@iq3_s}}
+    thinking: high
+    color: "#a78bfa"                 # optional hex — the agent's lane color in the visualizer
+    purpose: Turn a request into a plan the builder can implement without asking questions.
+    prompt_engineering:
+      system: apps/smidja/smidja_data/prompt_engineering/planner/system.md
+      user: apps/smidja/smidja_data/prompt_engineering/planner/user.md
+    harness_engineering:
+      - apps/smidja/smidja_data/harness_engineering/subagents.ts    # registers the four subagent_* tools below
+    writes:                        # the plan is the only thing it may leave in the repo
+      - specs/
+    tools:                         # full recon + write for plan.md; no edit — the planner never touches repo files
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+      - subagent_create            # extension tools MUST be named here or they are filtered out
+      - subagent_continue
+      - subagent_list
+      - subagent_remove
+
+  - name: builder
+    color: "#22d3ee"
+    purpose: Implement the plan exactly; report every changed file in the envelope.
+    prompt_engineering:
+      system: apps/smidja/smidja_data/prompt_engineering/builder/system.md
+      user: apps/smidja/smidja_data/prompt_engineering/builder/user.md
+    # No `writes` key: unrestricted, and the only agent that is. It still cannot
+    # touch defaults.protected_files — the builder does not get to edit its own grader.
+    tools:                         # the only agent that mutates the repo — everything on
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - edit
+      - write
+
+  - name: scout
+    color: "#fbbf24"
+    purpose: Find and report where things live; change nothing.
+    prompt_engineering:
+      system: apps/smidja/smidja_data/prompt_engineering/scout/system.md
+      user: apps/smidja/smidja_data/prompt_engineering/scout/user.md
+    harness_engineering:
+      - apps/smidja/smidja_data/harness_engineering/subagents.ts    # registers the four subagent_* tools below
+    writes: []                     # read-only, and now actually read-only: its findings
+                                   # go to context_handoff/, which is runtime, not the repo
+    tools:                         # search-heavy recon; write only so scout_findings.md lands without a bash heredoc
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+      - subagent_create            # extension tools MUST be named here or they are filtered out
+      - subagent_continue
+      - subagent_list
+      - subagent_remove
+
+  # No tester agent: running the suite is a known command, so it is a kind="code"
+  # phase over smidja_modules/quality.py. See SKILL.md hard rule 8.
+
+  - name: reviewer
+    model: ${SMIDJA_REVIEWER_MODEL:-${SMIDJA_LOCAL_MODEL:-llama-cpp/qwen3.6-35b-a3b@iq3_s}}
+    thinking: high
+    color: "#fb7185"
+    purpose: Confirm that what was built is what was asked for; change nothing.
+    prompt_engineering:
+      system: apps/smidja/smidja_data/prompt_engineering/reviewer/system.md
+      user: apps/smidja/smidja_data/prompt_engineering/reviewer/user.md
+    writes: []                     # a reviewer that cannot fix cannot quietly fix — the
+                                   # claim the tool list only implied, now enforced
+    tools:                         # full read surface; write only for review.md, no edit
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+
+  - name: documenter
+    model: ${SMIDJA_DOCUMENTER_MODEL:-${SMIDJA_LOCAL_MODEL:-llama-cpp/qwen3.6-35b-a3b@iq3_s}}
+    color: "#e879f9"
+    purpose: Write up the change that was just made, from the diff; document only.
+    prompt_engineering:
+      system: apps/smidja/smidja_data/prompt_engineering/documenter/system.md
+      user: apps/smidja/smidja_data/prompt_engineering/documenter/user.md
+    writes:                        # documentation only — "document only" is a rule now,
+      - app_docs/                  # not a line in a prompt the model may drift from.
+      - docs/                      # Markdown anywhere, because docs live next to the
+      - "**/*.md"                  # code they describe as often as in a docs folder.
+      - "*.md"
+    tools:                         # reads the diff and the code; writes/edits documentation only
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+      - edit

package/apps/smidja-factory/AGENTS.md

@@ -0,0 +1,165 @@
+---
+name: smidja
+description: Smíðja — the smithy. Deploy and operate repeatable agents+code workflows in any codebase. Use when installing the workshop, creating/running/updating a smithy, managing the agent roster in smidja.config.yaml, or observing running agent workflows. For LAUNCHING runs use the sibling skills smidja-launcher / smidja-start. Keywords - smidja, smithy, AI developer workflow, agent pipeline, install smithy.
+argument-hint: "[install | create smithy | run smithy | update config | ...]"
+---
+
+# Smíðja — the Smithy
+
+> **Norse name:** **Smíðja** (the smithy). Its orchestrator seat is **Völundr**,
+> the master smith — Smíðja's orchestrator (Kaia's seat inside the smithy).
+> Registry: `.agents/assets/agents/naming.md`, `docs/lore.md` §XI.
+
+Reusable combination of **agents plus code**: deterministic Python smidja scripts own sequencing, retries, and acceptance; coding agents (Pi in v1) work inside bounded phases; typed JSON envelopes carry context between them; everything streams into SQLite for the polled visualizer. Agent proposes, code disposes.
+
+## Sibling skills — load one if the task matches
+
+This skill is the **internals** skill (cookbooks/references below). For running
+or starting agents, load the sibling instead:
+
+- **`smidja-launcher`** — the one-command launcher (`scripts/smidja`): run any
+  chain/mode/service, watch, audit, stop, learn, missions.
+- **`smidja-start`** — exactly how to start agents for work: teams
+  (rosters), local/online models, chains, orchestrator, gotchas.
+- **`smidja-instructions`** — turn a vague ask into a runnable request file.
+- **`smidja`** — conventions when working inside `~/Ymir`.
+
+## Current runtime (verified 2026-08-31)
+
+- **Coding agents:** `pi` for local/LM Studio rosters (default config:
+  `coding_agent: pi`), `opencode` (via the `ocrd` profile) for cloud rosters.
+- **Default model:** `lmstudio/qwen3.5-9b` (from `smidja.config.yaml`:
+  `${SMIDJA_LOCAL_MODEL:-lmstudio/qwen3.5-9b}`). Full model surface: local
+  qwen3.5-4b/9b, gemma-4-12b-it, qwen3.6-35b-a3b quants, frontend-design-expert-8b;
+  cloud deepseek-v4-flash / big-pickle / nemotron-3-ultra-free — see
+  `smidja/smidja_smidja_config/roster.yaml` (the `tiers:` block).
+- **Rosters/teams:** `smidja/smidja_smidja_config/roster.yaml` — the ONE file (stacks,
+  roles, tools, writes + the `tiers:` model catalog). `smidja rosters` lists/validates.
+  - **Scaffold commands** (safe writes to that one file): `smidja team list|show|
+    new|smoke`, `smidja agent new`, `smidja model set|pin`, and `smidja doctor` (the
+    spawn-readiness check that must be green — refuses a 4B orchestrator/planner/reviewer).
+  - `roster.yaml` = the named teams (stacks) — pick one with `--roster <name>` /
+    `SMIDJA_ROSTER=<name>`; each stack lists its agents and per-agent model/tools.
+    `tiers:` = the model catalog — every role × backend tier (local,
+    local-agile, local-max, local-ui, cloud, cloud-free, cloud-reasoning,
+    hybrid-plan-local, hybrid-build-local, review) + `--model`/`SMIDJA_*_MODEL`
+    override surface.
+- **`justfile` (repo root):** the starter recipes — `just scout/sdlc/
+  simple-sdlc/orchestrate` run chains, `just sessions/phases/tail/procs/obs`
+  watch and open the UI. It calls `smidja-resolve-config`, honoring
+  `SMIDJA_CONFIG` → `SMIDJA_ROSTER` → `SMIDJA_MODEL_TIER` → default `smidja.config.yaml`.
+- **Visualizer ships with this skill:** `apps/visualizer/` (Vue + vite server).
+  Start with `just ui` / `scripts/smidja ui` → UI `http://localhost:4601`, API
+  `:4600`, Kaia memory `#/memory`. Sqlite probing still works — the db is WAL.
+- **Bench missions:** `tests/local-models/missions/` (T1 recon, T2 build, T3
+  context probe) via `smidja mission T1|T2 [--config <roster>]`; results in
+  `tests/local-models/RESULTS.md`.
+- **Deep-reference docs:** `docs/` — `software-smidja.md`
+  (overview), `software-smidja-run.md` (how to run), `software-smidja-pi.md` /
+  `software-smidja-opencode.md` (coding-agent setups), `software-smidja-visualizer.md`
+  (trace UI), `SmidjaAgentsAndModels.md` (roster + model backends source of
+  truth, incl. reasoning/write-scope per agent), `wayoffactory-updates.md`.
+
+## Startup
+
+Three steps. Then stop.
+
+1. Read [cookbooks/smidja_overview.md](cookbooks/smidja_overview.md) — the system map.
+2. `ls smidja/smidja_*.py` and read each file's `Phases:` docstring line.
+3. Print the smidja as a table — name, the chain, one line on when to reach for it — and **wait for the engineer's request.**
+
+```
+| smidja | Chain | Use when |
+|---|---|---|
+| smidja_scout | engineer → scout | read-only recon; nothing changes |
+| smidja_simple_sdlc | plan → build → test → review → document, 3 commits | the work is real and its shape is not obvious |
+```
+
+**Nothing else.** No trace-db queries, no reading the config or the smidja scripts' bodies, no repo inventory, no last-runs summary, no diagnosing an old failure, no "current state" dashboard. None of it was asked for, and it is not free:
+
+- **Volunteered state is guessed state.** An orchestrator that improvised a status board queried a `runs` table and a `payload` column — neither exists (`sessions`, `payload_json`). The spec that would have said so is `references/observability.md`, one lazy read away. Probing to look prepared is how you end up confidently wrong in your first message.
+- **It spends the context the real task needs**, before you know what the task is.
+- **It is stale on arrival.** State printed before the request describes a system that the very next run changes.
+
+Everything else — the db schema, the roster, the handoff contract — is lazy-loaded through the routing table below, when a request actually calls for it. Reading it early defeats the mechanism.
+
+Two exceptions, both narrow: if the engineer's first message already contains a request, skip the waiting and route it; and if the smidja is plainly not installed (no `smidja/`, no config), say that in one line instead of the table.
+
+## Orchestrator rules
+
+You run the system, observe the system, and help the user interact with it. **You do no smidja work yourself:**
+
+- Never implement, plan, or test in an agent's place — launch the smidja and watch it.
+- Never edit files inside `smidja/smidja_data/sessions/` — that is the run record.
+- Observe by querying `smidja/smidja_data/smidja.db` (WAL — reads never block writers) **when observing is the task**. This is a capability, not a startup step: query it to follow a run you launched or one the engineer asked about, never to volunteer a status report nobody requested.
+- Report phase status plainly: name, owner, status, error if any.
+
+## Request routing (lazy-load the cookbook, then follow it)
+
+| Request | Cookbook |
+|---|---|
+| `/smidja install`, set up the smidja in this repo | [cookbooks/install.md](cookbooks/install.md) |
+| create a new smidja / workflow | [cookbooks/create_adw.md](cookbooks/create_adw.md) |
+| modify an existing smidja chain | [cookbooks/update_adw.md](cookbooks/update_adw.md) |
+| create the config / agent roster | [cookbooks/create_config.md](cookbooks/create_config.md) |
+| add or retune an agent (model, thinking, tools, prompts) | [cookbooks/update_config.md](cookbooks/update_config.md) |
+| extend smidja_modules with new low-level logic | [cookbooks/update_modules.md](cookbooks/update_modules.md) |
+| run / monitor an smidja | [cookbooks/how_to_prompt_for_the_eng.md](cookbooks/how_to_prompt_for_the_eng.md) **first**, then [cookbooks/run_adw.md](cookbooks/run_adw.md) |
+| turn a request into an smidja prompt | [cookbooks/how_to_prompt_for_the_eng.md](cookbooks/how_to_prompt_for_the_eng.md) |
+
+Deep specs, when needed: [references/config.md](references/config.md) · [references/handoff.md](references/handoff.md) · [references/observability.md](references/observability.md)
+
+## Hard rules (enforced across everything the smidja generates)
+
+1. **Validate before running** — every smidja declares `REQUIRED_AGENTS` and calls `agents.validate()` first; a missing/misnamed agent fails before anything spawns.
+2. **Typed outputs only** — every agent call pairs with a concrete `EnvelopeBase` subclass in `smidja_modules/data_types.py`; parse failures re-prompt the same session (context intact), never restart.
+   **The output contract is a synced triad**: (a) the type in `data_types.py`, (b) the JSON example in the agent's `user.md` `## Report` section, (c) `output_type=` at every call site. These are ONE contract — change any one, update all three in the same edit (grep the type name to find every call site).
+3. **Gates validate claims, not guesses** — `gate(envelope, run) -> list[str]` violations; failures return to the same session as corrections.
+4. **Four-param rule** — any function with more than 4 parameters takes one concrete data type instead (`AgentCall`, `PhaseParams` are the pattern).
+5. **One agent, one prompt, one purpose** — identity lives in `system.md`; task shape (user prompt + output type) lives at the call site.
+6. **smidja scripts stay thin** — all low-level logic lives in `smidja_modules/`.
+7. **Every phase earns a description** — one sentence on what it does and why, never a restatement of its name. It is the only intent the trace, the console, and the UI ever show; `commit_plan: "Commit the plan"` is rejected at construction, blank is too.
+8. **A known command is code, not an agent** — if you can write the invocation down (`bun test`, `ruff check`), it belongs in a `kind="code"` phase via `smidja_modules/quality.py`. Agents are for the parts that need reading and deciding; failures come back to the builder as an envelope either way.
+9. **`tools:` is a capability list, `writes:` is the boundary** — `bash` runs anything (including `git checkout`) and `write` reaches any path, so a tool list can never make "this agent changes nothing" true. `writes:` per agent and `protected_files` in defaults are enforced in `smidja_modules/permissions.py` after every agent call: unauthorized changes are rolled back and the phase dies. The session runtime under `data_dir` is always writable — a read-only agent is read-only with respect to the REPO, never mute.
+10. **Every smidja ends in `run.finish()`** — phases passing is not the same as the run being accepted. A test phase that ran a red suite succeeded at its job. Pass `accepted=` so the exit code, the session status, and the banner are decided together and cannot disagree.
+
+## current scope (2026-09-01)
+
+Written back after the loss audit (see
+`docs/audits/old-vs-new-system-loss-audit-2026-09-01.md` and the recovery plan
+`plans/getback-lost-functionality-plan.md`) so the doc carries an honest,
+reader-visible statement of what the runtime is and does today:
+
+- **Orchestration:** `smidja_orchestrate` — Kaia (orchestrator) dispatches real
+  sub-agents via the `task` tool on BOTH surfaces (opencode's native dispatch
+  and pi's merged `subagents.ts` harness behave identically), tracks them, and
+  reports every changed file. Lanes appear live the moment a dispatch starts
+  (`_materialize_subagent_start` at `tool_execution_start`, role inferred via
+  `_infer_task_role`); the terminal materializer closes the same lane.
+- **Surfaces:** pi for local / LM Studio rosters; opencode (`ocrd` profile) for
+  cloud rosters. Default roster `local-12b` (local pi + LM Studio models).
+- **Visualizer:** live at `:4601` (API `:4600`) with sessions / trace / memory
+  / decisions / stats / **chat** views. The chat sidebar's "Past sessions" is
+  all-inclusive (`/api/sessions?scope=all`); Stop / Pause / Resume / steer are
+  wired; detached/terminal-launched runs auto-attach to the chat. Both the
+  neutral theme (default) and the preserved classic deep-space theme
+  (`data-theme="classic"` toggle in the topbar) are available.
+- **Stability:** a LM Studio GPU-kernel stall on a live pi child is detected by
+  the watchdog (`stall_watch.py`), traced as `model_stall`, cleared by
+  unload→reload, and the child is killed so the model-fallback retry resumes.
+- **Memory:** Kaia's engram under `smidja/smidja_data/kaia.engram` (UI `#/memory`,
+  CLI `just kaia`), project-aware per repo.
+- **Gates:** all 7 original gates preserved + `tools_were_used`, `loop_guard`,
+  `orchestrator_dispatched`.
+
+Everything is additive: old routes, tools, commands, widgets, data models and
+themes remain; new capability is layered on top.
+
+## v1 scope (updated to current stack)
+
+Local rosters run on **pi** with LM Studio models (`lmstudio/*`); cloud rosters
+run on **opencode** under the `ocrd` profile (`opencode-go/deepseek-v4-flash`
+workhorse, `opencode/big-pickle` free, `opencode/nemotron-3-ultra-free`
+reasoning). `claude_code` is schema-valid but stubbed until v2. The visualizer
+ships in `apps/visualizer/` (see Current runtime above) — `just ui` / `smidja ui`
+starts it; sqlite probing also works while it runs.

package/apps/smidja-factory/README.md

@@ -0,0 +1,3 @@
+# smidja-factory — the smithy — agent factory: roster, phases, envelopes, visualizer
+
+See `SKILL.md` for the full skill.

package/apps/smidja-factory/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: smidja
+description: >-
+  Smíðja — the smithy, the agent factory. Load when working on the smithy itself:
+  the agent roster and phases, phase envelopes, the trace/sessions store, or the
+  Visualizer UI (:8437). Load before changing agent factory behaviour, install,
+  or the visualizer.
+allowed-tools: read,write,bash,glob,grep
+---
+
+# smidja-factory — the smithy — agent factory: roster, phases, envelopes, visualizer
+
+The smithy forges and runs workers. Völundr is its master craftsman.
+
+- **Full reference:** `AGENTS.md` (in this folder) — the canonical smithy doc.
+- **Scripts:** `scripts/` · **Visualizer UI:** `apps/visualizer` (:8437).
+- **Install/ports/observer:** `.agents/skills/galdr-ymirsystem/assets/smidja.md`.
+- **Runtime:** `bin/smidja-bootstrap.sh`, the Session/Trace/Decisions/Stats gates.

package/apps/smidja-factory/apps/visualizer/.oxlintrc.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn", "oxc"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "perf": "warn"
+  },
+  "env": {
+    "browser": true,
+    "es2024": true
+  },
+  "rules": {
+    "no-console": "off",
+    "typescript/no-explicit-any": "warn"
+  },
+  "ignorePatterns": ["dist/**", "node_modules/**"]
+}