@zerwiz/ymir 0.1.33 → 0.1.35

package/apps/smidja-factory/skills/add-or-edit-ai-models/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: add-or-edit-ai-models
+description: "Tune the model (and prompt, and injected context) for agents, by interviewing the user first. Ask a lot of questions — which team(s) and role are affected, what they value (reasoning vs speed vs cost vs context), local/cloud/hybrid surface, exact model id, and whether they also want to tune the prompt or what gets injected — then hand-edit the roster file (+ prompt pair), validate in the catalog, and re-run. Use when the user wants to change an agent's model, add a model, fine-tune prompts, or control what context is injected into agents."
+version: "1.0"
+allowed-tools: read, write, edit, bash, grep, glob
+---
+
+# Add / Edit AI Models — tune model, prompt, and injection, after asking
+
+## Sibling skills
+- **`create-new-teams`** / **`create-new-agent`** — creating teams and roles.
+- **`smidja` / `smidja-launcher` / `smidja-start`** — running them.
+- **`smidja`** — conventions when work lands in `~/Ymir`.
+
+## When to use
+- User says: "change the builder's model", "that agent is too weak/slow",
+  "what can run the planner locally?", "give the team more context",
+  "the reviewer needs to see the spec" — model, prompt, or injection tuning.
+
+## The three dials (all hand-editable)
+1. **Model** — per (team × agent), in the roster file (`stacks` → per-agent
+   `models:` / `tiers:` (the model catalog lives in the same file).
+2. **Prompt** — `smidja/smidja_data/prompt_engineering/<name>/{system,user}.md`.
+   Who the agent is, and the task template.
+3. **Injection** — what goes into the agent's context before it works: the
+   team's `inject:` list (AGENTS.md, skills, memory, prior spec) and the
+   `{{…}}` slots in `user.md`. Tune these to shape what the agent sees.
+
+## 0. Interview — ASK THE USER, do not guess
+
+| # | Question | Why it matters |
+|---|---|---|
+| 1 | **Which scope?** One team, a few teams, or everywhere (a shared preset/tier)? | Decides where the edit lands: one stack's `models:` vs the shared preset. |
+| 2 | **Which role(s)?** orchestrator/planner/builder/scout/reviewer/documenter/… | The per-agent target. |
+| 3 | **What is wrong / what do you value?** Speed? Quality/reasoning? Context length? Cost (free?)? Privacy/local? | The selection criteria — the answer changes the pick. |
+| 4 | **Local, cloud, or hybrid?** And do we have the surface (VRAM / keys)? | Narrows the catalog. |
+| 5 | **Exact model id, or should I pick?** You pick → state candidates + your choice before editing. | The **provider/model-id** to write. |
+| 6 | **Prompt too?** Also tune `system.md` (who it is) or `user.md` (task template / what's injected)? | Branches into prompt editing — the triad rule applies. |
+| 7 | **Injection?** Which context should it see — AGENTS.md, project skills, knowledge/memory, a prior spec, git log? | Fills the `inject:` list / `user.md` slots. |
+| 8 | **Same or different across teams?** Same role, but different model per team? | Per-team assignment semantics. |
+
+If the user says "you pick": keep the role's current class, improve one axis
+they named, prefer local where VRAM/keys permit, and say exactly what you chose
+and why.
+
+## 0. Fast path — let the scaffold set it
+
+`smidja model set` writes the exact change below (and `model pin <stack> <role>
+<model>` is its alias), validates the string against known providers (+ the LM
+Studio catalog for `lmstudio/`), and refuses a small model on
+orchestrator/planner/reviewer:
+
+```bash
+smidja model set cloud-free orchestrator openrouter/qwen3.5-235b-a22b:free   # shared tier
+smidja model set local-ui builder lmstudio/frontend-design-expert-8b          # one team (override)
+smidja model pin  local-ui builder lmstudio/frontend-design-expert-8b         # alias, stack-forced
+smidja doctor --stack local-ui   # green = applied + legal
+```
+The change below is identical — hand-edit only when the export is the point
+(machine-verified either way).
+
+## 1. Change the model (per team × agent)
+
+In `smidja/smidja_smidja_config/roster.yaml`, target the exact scope:
+
+```yaml
+# one team only — override just that agent (the runtime resolver reads overrides.<role>.model)
+stacks:
+  my-team:
+    agents: [orchestrator, planner, builder, scout, reviewer, documenter]
+    overrides:
+      orchestrator:
+        model: lmstudio/qwen3.6-35b-a3b@q2_k_xl   # the big one
+      builder:
+        model: lmstudio/qwen3.5-9b                # cheap + fast
+```
+
+```yaml
+# every team that uses a preset — edit the shared preset
+tiers:                 # the canonical key (was models.yaml tiers:; model_presets: is a resolver alias)
+  local:
+    builder: lmstudio/qwen3.5-9b          # ← change here = every local team
+```
+
+Selection rules (see `plans/model-team-agent-playbook.md` §1):
+- **orchestrator/planner/reviewer** → strong reasoning + long context; **never
+  4B**. Reviewer default: `gemma-4-12b-it@q4_k_m` ("deep but cheap").
+- **builder** → fast/cheap executor (`qwen3.5-9b`, `qwopus3.5-9b-coder`,
+  `frontend-design-expert-8b` for UI).
+- **scout** → the only 4B slot is fine; 9b for depth.
+- Always write `provider/model-id` (a bare id that matches several providers
+  raises at validation). Changing an agent's model = fresh session (context
+  window does not carry across a model change — intended).
+
+## 2. Validate against the real catalog before re-running
+
+```bash
+curl -s http://localhost:1234/v1/models | python3 -c "import json,sys;print('\n'.join(m['id'] for m in json.load(sys.stdin)['data']))"   # local
+smidja doctor                    # planned: models resolve, prompts exist, no 4B coordinator
+smidja rosters                   # show what each stack resolves to today
+```
+A local id missing from `:1234` will fail at spawn — catch it here, in a second,
+not halfway through a run.
+
+## 3. Tune the prompt (hand-edit)
+
+`system.md` — who the agent is. If the `purpose` changes, edit the role entry
+AND the system `Purpose` in the same edit (they must not drift).
+
+`user.md` — the task template. The injection slots you can shape:
+- `{{prompt}}` — the incoming ask (never edit this).
+- `{{previous_envelope}}` — prior agent's typed output (cross-team context).
+- `{{context_handoff_dir}}` — files other agents left for it.
+- Anything else the agent must always see → add to the team's `inject:` list or
+  append to the template.
+
+**Triad rule:** prompt changes that touch the output contract must stay in sync
+with `data_types.py` and the call site's `output_type=` — one edit, three files.
+
+## 4. Tune injection (what the system feeds the agent)
+
+The `stacks:` `inject:` list and per-agent `user.md` control what context enters
+the window:
+```yaml
+stacks:
+  my-team:
+    inject:
+      - AGENTS.md                       # project rules the builder must follow
+      - smidja/smidja_data/knowledge/team-notes.md   # domain memory
+```
+Keep injection lean — every injected file spends the agent's context window on
+setup instead of work. When in doubt, smaller + focused beats bigger + diffuse.
+
+## 5. Re-run and confirm
+
+```bash
+smidja run --roster my-team "<ask>"
+```
+Check the trace (:4601): the changed lane shows the new model, and the
+injected context shows up in the agent's transcript. Report what changed and
+what the run showed.
+
+## Golden rules
+1. **Ask before you edit.** Scope (which team/role), the axis (speed/quality/
+   context/cost), the surface (local/cloud), and exact id come from the user.
+2. **Per-team model is the default** — same role can differ across teams.
+3. **Never a 4B orchestrator/planner/reviewer** — `doctor` enforces it.
+4. **Validate in the catalog first** — a typo catches you in a second, not in
+   a run.
+5. **Prompt + output type + call site are one thing** (triad) — change all three.
+6. **Injection is a budget** — lean and focused, and visible in the transcript.

package/apps/smidja-factory/skills/create-new-agent/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: create-new-agent
+description: "Create a new agent role by interviewing the user first. Ask a lot of questions — the job/purpose, which existing role to clone from, which model it runs, thinking level, tools and write boundary, lane color, which teams should contain it, and what context/prompt to give it — then hand-edit the roster file and the prompt pair, and validate. Use when the user wants a new agent, a new role, a specialist ('make me a devops agent'), or an agent for a team that doesn't exist yet."
+version: "1.0"
+allowed-tools: read, write, edit, bash, grep, glob
+---
+
+# Create New Agents — ask first, then make the role real
+
+## Sibling skills
+- **`create-new-teams`** — teams (stacks) built from agent roles.
+- **`add-or-edit-ai-models`** — tuning an existing agent's model/prompt/injection.
+- **`smidja` / `smidja-launcher` / `smidja-start`** — running the team.
+- **`smidja`** — conventions when work lands in `~/Ymir`.
+
+## The one mental model
+**An agent is a role, defined once; it carries no model of its own.** A role =
+one `role_defaults:` entry (purpose, thinking, tools, writes, color) +
+one prompt pair (`smidja/smidja_data/prompt_engineering/<name>/{system,user}.md`).
+The model is assigned later, per team, in the stack. So creating an agent is
+creating the *role* — and every team that lists it gets a model for it.
+
+## When to use
+- User says: "make an agent for…", "we need a spec agent", "add a devops role",
+  "create a specialist like the wot-* ones".
+
+## 0. Interview — ASK THE USER, do not guess
+
+Go one question at a time. Minimum set:
+
+| # | Question | Why it matters |
+|---|---|---|
+| 1 | **What is this agent FOR?** The job, in one sentence — its `purpose`. | Fills `purpose`; must match the system prompt. |
+| 2 | **A brand-new role or a clone?** Any existing role to start from (planner/builder/scout/reviewer/documenter/orchestrator…)? | `--from <role>` seeds tools/writes/prompt pair. |
+| 3 | **Does it write, or is it read-only?** Changes in the repo vs reports only (`writes: []`). | Sets the `writes` boundary — the enforcement rule. |
+| 4 | **Which tools does it need?** read/bash/edit/write; grep/find/ls for search; `subagent_*` if it spawns subagents. | The `tools` allowlist (and the extension-tools-must-be-named rule). |
+| 5 | **How much thinking?** low (mechanical recon) / medium (executor) / high (judgement: coordinator, planner, reviewer). | Sets `thinking`. |
+| 6 | **Which model should it run?** Across which teams? Remind: this is per-team, decided in the stack — but ask what class of model it needs (big/strong context vs cheap/fast). | Feeds the model assignment. **Never 4B if it's an orchestrator/planner/reviewer.** |
+| 7 | **Which teams should contain it?** List stacks, or "later". | Registers it in stacks now or leaves it available. |
+| 8 | **What context should be injected?** AGENTS.md? domain skills? memory? prior envelope? | The prompt injection plan. |
+| 9 | **Lane color?** (optional — the UI swatch). | `color` hex; default from palette. |
+
+The user may answer "you pick": clone `planner` for a specialist, medium
+thinking, read+write as appropriate, cheap model, add to the current team.
+State your choices before writing.
+
+## 0. Fast path — let the scaffold write it
+
+`smidja agent new` appends the `role_defaults:` entry below, scaffolds the prompt
+pair, assigns a lane color, and refuses a bad name up front:
+
+```bash
+smidja agent new my-role --from planner \
+  --thinking medium --tools read,edit,write,bash,grep,find,ls \
+  --writes specs/ \
+  --purpose "<one sentence from the interview>"
+then:  smidja doctor    # green = roles known, prompts on disk
+```
+Hand-editing below stays valid — the scaffold writes the same block + prompt
+pair, and preserves every comment in the file.
+
+## 1. Hand-edit the role (roster file)
+
+Add the role to the `role_defaults:` block in `smidja/smidja_smidja_config/roster.yaml`:
+
+```yaml
+role_defaults:
+  my-role:
+    thinking: medium            # off|minimal|low|medium|high|xhigh|max
+    purpose: <one sentence from the interview>
+    tools: [read, bash, edit, write, grep, find, ls]   # or the list from Q4
+    writes: [specs/]            # [] = read-only; omit = any (minus protected)
+    color: "#22d3ee"            # optional lane swatch
+```
+
+Rules (origin `references/config.md`):
+- **tools** is an allowlist; omitted = all builtins. `grep/find/ls` are off in
+  bare pi — name them. If the role spawns subagents, add `subagent_*` tool names
+  **and** `harness_engineering: [smidja/smidja_data/harness_engineering/subagents.ts]`.
+- **writes** is the repo boundary enforced after every call: trailing `/` =
+  dir prefix, `*` one segment, `**` crosses, else exact path. `data_dir`
+  (reports/sessions) is always writable.
+- **thinking** is inert on non-reasoning models — set it anyway (portable).
+
+## 2. Write the prompt pair (hand-editable, tunable — the point)
+
+Create `smidja/smidja_data/prompt_engineering/<name>/system.md` and `user.md`:
+
+- `system.md` — who the agent is; repeat `purpose` verbatim (they must not
+  drift); its output contract.
+- `user.md` — the task template: `{{prompt}}`, `{{previous_envelope}}`,
+  `{{context_handoff_dir}}`, ends with a `## Report` JSON example. Anything else
+  the agent needs injected (AGENTS.md, skills, examples) can be appended here or
+  wired through the team's `inject:` list.
+
+**Triad rule:** the output *type* (`smidja/smidja_modules/data_types.py`), the
+`## Report` example (`user.md`), and `output_type=` at the smidja call site are one
+thing — change one, change all three in the same edit.
+
+Clone path shortcut: copying `planner`'s pair and editing the Purpose/Report
+sections is the fastest correct start.
+
+## 3. Register it
+
+- Add the name to the `agents:` list of any stack that should contain it
+  (then give it a model there — per team).
+- If an smidja should use it directly, list it in that smidja's `REQUIRED_AGENTS` /
+  phase `owner=` (smidja name agents, never models).
+
+## 4. Validate
+
+```bash
+smidja doctor          # planned: role exists, prompts present, model resolvable, no 4B coordinator
+```
+A role with no prompt pair or an unresolvable model fails before anything
+spawns — that's the design, not a bug.
+
+## Golden rules
+1. **Ask before you build.** The interview is the product.
+2. **An agent = role (no model) + prompt pair.** Models are per-team.
+3. **Prompt pair is hand-editable and tunable** — keep system `purpose` and
+   `user.md` `## Report` in sync with the output type (triad rule).
+4. **tools = capability, writes = boundary.** State both honestly.
+5. **A 4B role must never be orchestrator/planner/reviewer.**
+6. Validate before you trust it; add it to a team + smoke to see it live.

package/apps/smidja-factory/skills/create-new-teams/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: create-new-teams
+description: "Create a new smidja team (roster stack) by interviewing the user first. Ask a lot of questions — purpose, local/cloud/hybrid surface, which agents, which model EACH agent runs (orchestrator gets a big model by default), cost/speed/quality trade-offs, kaia tier, and what context to inject — then hand-edit the roster file and validate. Use when the user wants a new team, a new roster, a new configuration of agents+models, or 'make a team for project X'."
+version: "1.0"
+allowed-tools: read, write, edit, bash, grep, glob
+---
+
+# Create New Teams — ask first, then make the team real
+
+## Sibling skills
+- **`create-new-agent`** — a single new agent role (do this first if the team
+  needs a role that doesn't exist yet).
+- **`add-or-edit-ai-models`** — changing models/prompts/injection for an
+  existing team or agent.
+- **`smidja` / `smidja-launcher` / `smidja-start`** — running the team once it
+  exists.
+- **`smidja`** — conventions when work lands in `~/Ymir`.
+
+## The one rule
+**A team is a `stacks:` block in the roster file: which agents, and which model
+each one runs.** The model is a per-(team × agent) assignment — the same agent
+role runs a big model in one team and a cheap one in another. Hand-edit the
+file; never generate a throwaway config. Source of truth:
+`smidja/smidja_smidja_config/roster.yaml` — the ONE file: teams (`stacks:`), agent
+roles (`role_defaults:`), and the model catalog (`tiers:`) all live together
+after `models.yaml` was merged in (Sep 2026).
+
+## When to use
+- User says: "make a new team", "new roster for project X", "I want a team for
+  …", "how do I set up agents for this?".
+
+## 0. Interview — ASK THE USER, do not guess
+
+Do not open the file until you have answers. Go one question at a time; write
+down the answers. Ask at least these (adapt order to the conversation):
+
+| # | Question | Why it matters |
+|---|---|---|
+| 1 | **What is the team FOR?** Project/domain, in one sentence. | Defines purpose; may imply a specialized roster (e.g. WayOfTeams wot-*) vs generic SDLC. |
+| 2 | **Local, cloud, or hybrid?** Offline/private (LM Studio) vs cloud (opencode: bigger context, needs keys) vs mix (cloud plan/review, local build). | Picks the surface per agent; decides keys needed. |
+| 3 | **Full SDLC or specialized?** The 6 (orchestrator, planner, builder, scout, reviewer, documenter) — or a subset/specialists. | Shapes the `agents:` list. |
+| 4 | **Which agents exactly?** Name them (existing roles). If one doesn't exist, branch to `create-new-agent` first. | The stack's `agents:` list. |
+| 5 | **What model should EACH agent run?** Walk the list: orchestrator = big model (biggest context + strongest reasoning available); planner/reviewer = strong; builder/scout = fast + cheap. Ask per agent: "and for the builder?" | The per-agent model assignment — the heart of the stack. **Never a 4B orchestrator/planner/reviewer.** |
+| 6 | **Cost vs speed vs quality?** Cheap & fast (repetition-heavy builders/scouts), or depth (frontier/local-big for the coordinator). | Fine-tunes the picks. |
+| 7 | **Kaia tier?** T0 (none), T1 (admission notes, default), T2 (Kaia synthesizes/coordinates). | `kaia_tier` on the stack. |
+| 8 | **What should be injected into their context?** AGENTS.md? project skills? knowledge/memory? prior spec? | The `inject:` list (context sources per agent/team). |
+| 9 | **Name the team.** | The stack name (`smidja run --roster <name>`). |
+
+If the user answers "you pick", default: local surface, full 6, orchestrator on
+the largest local model, planner/reviewer mid-strong, builder/scout cheap, T1.
+State the defaults back before writing.
+
+## 0. Fast path — let the scaffold write it
+
+`smidja team new` emits the exact `stacks:` block you'd hand-write below, validates
+agents/tier/models immediately, and refuses a team with no models at all:
+
+```bash
+smidja team new my-team \
+  --agents orchestrator,planner,builder,scout,reviewer,documenter \
+  --tier local \
+  -m orchestrator=lmstudio/qwen3.6-35b-a3b@q2_k_xl \
+  -m builder=lmstudio/qwen3.5-9b \
+  --thinking builder=low \
+  --inject AGENTS.md \
+  --kaia-tier T1
+then:
+  smidja team show my-team     # expanded view: role → model/thinking/tools/writes
+  smidja doctor                # green = the team would spawn
+```
+Hand-editing below stays valid and is the same thing — the scaffold just does
+the boilerplate + validation and preserves every comment in the file.
+
+## 1. Hand-edit the roster (one file)
+
+Open `smidja/smidja_smidja_config/roster.yaml` and add the stack. Two ways to give the
+team its models — pick the one the interview produced:
+
+```yaml
+stacks:
+  my-team:
+    tier: local           # a named model set from the tiers: catalog (same file)
+    agents: [orchestrator, planner, builder, scout, reviewer, documenter]
+    overrides:            # per-team per-agent tuning; a model here wins over the tier
+      orchestrator:
+        model: lmstudio/qwen3.6-35b-a3b@q2_k_xl   # big model — the default
+      builder:
+        model: lmstudio/qwen3.5-9b                # cheap + fast
+        thinking: low
+    inject:               # context to inject into these agents
+      - AGENTS.md
+    kaia_tier: T1
+```
+
+```yaml
+# B) fully explicit — one model per agent, no tier
+stacks:
+  my-team:
+    agents: [orchestrator, planner, builder, scout, reviewer, documenter]
+    overrides:
+      orchestrator:
+        model: lmstudio/qwen3.6-35b-a3b@q2_k_xl
+      planner:
+        model: lmstudio/qwen3.6-35b-a3b@q2_k_xl
+      builder:
+        model: lmstudio/qwen3.5-9b
+      scout:
+        model: lmstudio/qwen3.5-4b
+      reviewer:
+        model: lmstudio/gemma-4-12b-it@q4_k_m
+      documenter:
+        model: lmstudio/qwen3.5-9b
+    kaia_tier: T1
+```
+
+Keep the shape honest: **each role may run a different model; the orchestrator
+usually runs a big one.** Never leave a team that silently runs one default
+model for everyone — say it explicitly.
+
+## 2. Validate before it runs
+
+```bash
+smidja doctor          # planned: prompts exist, models resolve, no 4B coordinator
+smidja rosters         # resolves every stack today — shows per-agent models
+```
+
+- Every agent on the `agents:` list must exist in `role_defaults:` and
+  have its prompt pair in `smidja/smidja_data/prompt_engineering/<name>/`.
+- Every model must resolve (local → present in `:1234/v1/models`; cloud →
+  opencode/pi catalog). A bare `provider/model` is mandatory.
+- **`doctor`/validate refuses: orchestrator|planner|reviewer on a 4B model.**
+
+## 3. Prove it spawns (the acceptance bar)
+
+```bash
+smidja run --roster my-team "<ask>"      # or SMIDJA_ROSTER=my-team …
+smidja team smoke my-team                # planned: cheap run, every lane visible in :4601
+```
+
+A new team is not real until **every member appears as a lane in the trace UI**
+(:4601) — orchestrator through documenter — and the run reaches green or a
+gate with teeth says why not. Report the `smidja_id` + what the trace showed.
+
+## Golden rules
+1. **Ask before you build.** The interview is the product.
+2. **One file is the source of truth** — hand-edit `roster.yaml`; never a
+   throwaway config, never a "random tweak".
+3. **The orchestrator runs a big model. Never a 4B.**
+4. **Per-agent models are the norm**, not a special case.
+5. **Validate + smoke before you call it done** — spawning in the UI is the bar.
+6. If the team needs a role that doesn't exist → `create-new-agent` first.

package/apps/smidja-factory/skills/git-ops/README.md

@@ -0,0 +1,25 @@
+# git-ops/ — WayOf Command
+
+Deterministic Git workflow. All source-control operations run through these scripts to protect repo history and enforce conventions.
+
+## What Goes Here
+
+- `SKILL.md` — Skill guidelines for Git operations.
+- `create_branch.sh` — Branch creation with proper naming & ticket linking.
+- `safe_commit.sh` — Pre-commit gates + commit message formatting.
+- `sync_upstream.sh` — Rebase & conflict checks.
+
+## File Pattern
+
+```
+git-ops/
+├── SKILL.md
+├── create_branch.sh
+├── safe_commit.sh
+└── sync_upstream.sh
+```
+
+## Rules
+
+- Git actions (branching, committing, rebasing) MUST go through these scripts — no bare `git commit -m ...`.
+- Pre-commit gates (lint, tests) run inside `safe_commit.sh` before anything is committed.

package/apps/smidja-factory/skills/git-ops/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: git-ops
+description: Routing for Git operations — create branches, safe commits with gates, and sync upstream. Use when the user needs to create a feature/fix branch, commit with gate validation, or rebase and push. All git operations go through these scripts; never run bare git commands.
+---
+
+# SKILL.md — git-ops
+
+Routing for Git operations.
+
+## Scripts
+| Command | Script | Usage |
+|---------|--------|-------|
+| create_branch | `create_branch.sh` | Create `feat/<feature>` / `fix/<ticket>` branch |
+| safe_commit | `safe_commit.sh` | Run gates, format message, commit |
+| sync_upstream | `sync_upstream.sh` | Rebase + conflict check + push |
+
+## Rules
+- Never run bare git commands outside these scripts.

package/apps/smidja-factory/skills/git-ops/create_branch.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# create_branch.sh — create a working branch, correctly named (git-ops).
+#
+# The house rule is that all git work goes through these three scripts, so a
+# branch is always named the same way, always based on the default branch, and
+# never created on top of uncommitted work (which is how a change ends up in two
+# branches at once).
+#
+# Usage:
+#   create_branch.sh <type>/<name> [--from <base>] [--allow-dirty]
+#     type   feat | fix | chore | docs | refactor | test   (what the change is)
+#     name   kebab-case slug, e.g. "electron-igpu-gpu-crash"
+#     --from <base>   branch from <base> (default: the repository default)
+#     --allow-dirty   create anyway with a dirty tree (reported, not hidden)
+#
+# Exit: 0 created, 1 refused, 2 usage.
+set -u
+
+VERSION="1.0.0"
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { printf 'error: not a git repository\n' >&2; exit 1; }
+cd "$ROOT" || exit 1
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+BRANCH="${1-}"; shift || true
+FROM=""; ALLOW_DIRTY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --from) FROM=${2-}; shift 2 ;;
+    --allow-dirty) ALLOW_DIRTY=1; shift ;;
+    *) printf 'error: unknown flag %s\nhelp: create_branch.sh <type>/<name> [--from <base>]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$BRANCH" ] || { printf 'error: no branch name\nhelp: create_branch.sh <type>/<name> [--from <base>]\n' >&2; exit 2; }
+
+# ── the name ─────────────────────────────────────────────────────────────────
+case "$BRANCH" in
+  */*) TYPE=${BRANCH%%/*}; SLUG=${BRANCH#*/} ;;
+  *) printf 'error: branch must be <type>/<name>, got %s\nhelp: types are feat|fix|chore|docs|refactor|test\n' "$BRANCH" >&2; exit 2 ;;
+esac
+case "$TYPE" in
+  feat|fix|chore|docs|refactor|test) : ;;
+  *) printf 'error: unknown type %s\nhelp: feat|fix|chore|docs|refactor|test\n' "$TYPE" >&2; exit 2 ;;
+esac
+printf '%s' "$SLUG" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$' || {
+  printf 'error: name must be kebab-case (a-z, 0-9, single dashes): %s\n' "$SLUG" >&2; exit 2; }
+
+# ── the base ─────────────────────────────────────────────────────────────────
+if [ -z "$FROM" ]; then
+  FROM="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+  [ -n "$FROM" ] || FROM=main
+fi
+git rev-parse --verify --quiet "$FROM" >/dev/null || {
+  printf 'error: base branch not found: %s\nhelp: fetch first (git-ops/sync_upstream.sh --check) or pass --from\n' "$FROM" >&2; exit 1; }
+
+# ── the tree ─────────────────────────────────────────────────────────────────
+DIRTY=$(git status --porcelain | wc -l | tr -d ' ')
+if [ "$DIRTY" != 0 ] && [ "$ALLOW_DIRTY" = 0 ]; then
+  printf 'branch[1]{branch,state,detail}:\n  "%s","refused","%s uncommitted path(s) would follow you onto the new branch"\n' \
+    "$BRANCH" "$DIRTY"
+  printf 'help[1]{do}\n  "commit them (git-ops/safe_commit.sh), stash them, or pass --allow-dirty"\n' >&2
+  exit 1
+fi
+
+git rev-parse --verify --quiet "$BRANCH" >/dev/null && {
+  printf 'error: branch already exists: %s\nhelp: pick another name, or switch to it with git switch\n' "$BRANCH" >&2; exit 1; }
+
+# ── create ───────────────────────────────────────────────────────────────────
+if ! git checkout -q -b "$BRANCH" "$FROM" 2>/dev/null; then
+  printf 'error: could not create %s from %s\n' "$BRANCH" "$FROM" >&2; exit 1
+fi
+
+printf 'branch[1]{branch,from,base_sha,dirty}:\n  "%s","%s","%s",%s\n' \
+  "$BRANCH" "$FROM" "$(git rev-parse --short HEAD)" "$DIRTY"
+printf 'next[2]{step,command}:\n  "work","edit, then git-ops/safe_commit.sh -m ..."\n  "land","git-ops/sync_upstream.sh (pushes through the no-mistakes gate)"\n'
+exit 0

package/apps/smidja-factory/skills/git-ops/safe_commit.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# safe_commit.sh — run the house gates, then commit (git-ops).
+#
+# A commit that has not passed the gates is a commit that will fail later, in CI
+# or in review, where it costs more. The gates are the repo's own, so local and
+# CI cannot diverge. Pushing is NOT done here — that is the gate's job
+# (sync_upstream.sh routes through no-mistakes).
+#
+# Usage:
+#   safe_commit.sh -m "<type>(<scope>): <subject>" [--all] [--no-gates]
+#
+# Exit: 0 committed, 1 refused by a gate or by git, 2 usage.
+set -u
+
+VERSION="1.0.0"
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { printf 'error: not a git repository\n' >&2; exit 1; }
+cd "$ROOT" || exit 1
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+
+MSG=""; ALL=0; GATES=1
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -m|--message) MSG=${2-}; shift 2 ;;
+    --all) ALL=1; shift ;;
+    --no-gates) GATES=0; shift ;;
+    *) printf 'error: unknown flag %s\nhelp: safe_commit.sh -m "<message>" [--all] [--no-gates]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$MSG" ] || { printf 'error: a commit message is required\nhelp: safe_commit.sh -m "<type>(<scope>): <subject>"\n' >&2; exit 2; }
+
+# conventional shape, because the log is read by agents and by humans
+printf '%s' "$MSG" | head -1 | grep -qE '^(feat|fix|chore|docs|refactor|test|perf|build|ci)(\([a-z0-9._/-]+\))?: .+' || {
+  printf 'error: message must be conventional: type(scope): subject\nhelp: types are feat|fix|chore|docs|refactor|test|perf|build|ci\n' >&2; exit 2; }
+
+# ── stage ────────────────────────────────────────────────────────────────────
+if [ "$ALL" = 1 ]; then git add -A; else git add -u; fi
+STAGED=$(git diff --cached --name-only | wc -l | tr -d ' ')
+[ "$STAGED" != 0 ] || { printf 'commit[1]{state,detail}:\n  "nothing","no staged changes (use --all to include new files)"\n'; exit 1; }
+
+# ── gates ────────────────────────────────────────────────────────────────────
+declare -a G S
+if [ "$GATES" = 1 ] && [ -d "$ROOT/.compliance/gates" ]; then
+  for g in "$ROOT"/.compliance/gates/*.sh; do
+    [ -x "$g" ] || continue
+    n=$(basename "$g" .sh)
+    if bash "$g" >/dev/null 2>&1; then G+=("$n"); S+=("pass"); else G+=("$n"); S+=("FAIL"); fi
+  done
+fi
+if [ "$GATES" = 1 ] && [ -x "$ROOT/.agents/skills/galdr-ymirsystem/scripts/compliance-check.sh" ]; then
+  if bash "$ROOT/.agents/skills/galdr-ymirsystem/scripts/compliance-check.sh" >/dev/null 2>&1; then G+=("compliance"); S+=("pass"); else G+=("compliance"); S+=("FAIL"); fi
+fi
+if [ "$GATES" = 1 ] && [ -x "$ROOT/bin/brokk-lint.sh" ]; then
+  if bash "$ROOT/bin/brokk-lint.sh" >/dev/null 2>&1; then G+=("lint"); S+=("pass"); else G+=("lint"); S+=("FAIL"); fi
+fi
+
+bad=0
+for s in "${S[@]:-}"; do [ "$s" = FAIL ] && bad=1; done
+if [ "$bad" = 1 ]; then
+  printf 'commit[1]{state,detail}:\n  "refused","a gate failed — nothing was committed"\n'
+  ng=${#G[@]}
+  printf 'gates[%s]{gate,status}:\n' "$ng"
+  if [ "$ng" -gt 0 ]; then
+    for i in $(seq 0 $((ng - 1))); do printf '  "%s","%s"\n' "${G[$i]}" "${S[$i]}"; done
+  fi
+  printf 'help[1]{do}\n  "fix the failing gate, or pass --no-gates to commit anyway (say why in the message)"\n' >&2
+  exit 1
+fi
+
+# ── commit ───────────────────────────────────────────────────────────────────
+if ! git commit -q -m "$MSG"; then
+  printf 'commit[1]{state,detail}:\n  "failed","git refused the commit — see the output above"\n' >&2; exit 1
+fi
+printf 'commit[1]{sha,paths,message}:\n  "%s",%s,"%s"\n' \
+  "$(git rev-parse --short HEAD)" "$STAGED" "$(printf '%s' "$MSG" | head -1 | cut -c1-60)"
+ng=${#G[@]}
+printf 'gates[%s]{gate,status}:\n' "$ng"
+if [ "$ng" -gt 0 ]; then
+  for i in $(seq 0 $((ng - 1))); do printf '  "%s","%s"\n' "${G[$i]}" "${S[$i]}"; done
+fi
+printf 'next[1]{step,command}:\n  "land","git-ops/sync_upstream.sh — pushes through the no-mistakes gate"\n'
+exit 0