arkaos 4.19.0 → 4.21.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-86 agents. 17 departments. 283 skills. Enterprise frameworks. Multi-runtime. One install.
+86 agents. 17 departments. 290 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install

package/VERSION

@@ -1 +1 @@
-4.19.0
+4.21.0

package/arka/SKILL.md

@@ -25,7 +25,7 @@ measures citation compliance per turn.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 86 agents. 17 departments. 283 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 290 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/departments/dev/skills/exploit-triage/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: dev/exploit-triage
+description: >
+  Reviews code for the vulnerabilities that are actually reachable and
+  actually exploitable — SSRF, auth bypass, injection, insecure
+  deserialisation, IDOR — biased toward a remote, unauthenticated
+  attacker, and discards the theoretical. Answers "can someone reach and
+  weaponise this?", not "is this textbook-perfect?". TRIGGER: "/dev
+  exploit-triage", "is this exploitable", "attack surface", "can this be
+  reached", "SSRF/IDOR/auth bypass", "isto é explorável?", "que dano real
+  se tira daqui?"; run on a diff touching auth, input handling, requests,
+  deserialisation, or file/db access. SKIP: broad OWASP/quality pass ->
+  dev/security-audit wins; adversarially breaking a diff (abuse cases,
+  threat-modelling a change) -> dev/adversarial-review wins; planning a
+  full offensive engagement (signed RoE, ATT&CK campaign) -> dev/red-team
+  wins; agent/prompt-injection threats -> dev/ai-security wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# Exploit Triage — `/dev exploit-triage`
+
+> **Agent:** Bruno (Security Engineer) | **Framework:** Reachability-first, attacker-economics, CWE Top 25
+
+A security review that lists every theoretical weakness buries the one
+that gets you breached. This lens inverts the priority: it starts from a
+remote, unauthenticated attacker and asks, of each finding, whether they
+can reach the code path and whether reaching it actually pays. A missing
+security header on an internal admin page is a note; an SSRF on a
+user-supplied URL that reaches the cloud metadata endpoint is the report.
+Reachability and impact rank everything; the textbook comes second.
+
+## What to hunt (reachability-first)
+
+| Class | The question that decides severity |
+|-------|-----------------------------------|
+| **SSRF** (CWE-918) | Does a user-controlled URL/host reach a fetch, and can it hit internal services or a metadata endpoint? |
+| **Auth / access bypass** (CWE-287/862, IDOR CWE-639) | Can the check be skipped, or an object accessed by ID without ownership (IDOR)? |
+| **Injection** (CWE-74: SQLi/command/template) | Does untrusted input reach a query, a shell, or a template unparameterised? |
+| **Insecure deserialisation** (CWE-502) | Is attacker-controlled data deserialised into objects (pickle, unsafe YAML, native serialisers)? |
+| **Path traversal / upload** | Can a user steer a file path or upload an executable/served type? |
+| **Secrets & SSRF-adjacent** | A leaked credential or an open redirect that chains into the above. |
+
+## Process
+
+1. Map the **entry points** in the diff — what an unauthenticated request can reach, then what an authenticated-but-untrusted user can.
+2. For each candidate, trace the taint: does attacker input reach the sink, and is there a real control in the way?
+3. Rank by **reachability × impact**, not by CWE checklist order. Discard the theoretically-imperfect-but-unreachable with a one-line note, so the real findings are not buried.
+4. For each real finding, give the **concrete attack** (the request an attacker sends) and the fix.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a user-supplied URL or hostname flowing into an HTTP client → the SSRF, and whether it can reach the metadata endpoint
+- an object fetched by an ID from the request with no ownership check → the IDOR and the horizontal access it grants
+- `pickle.loads` / `yaml.load` / a native deserialiser on request data → the deserialisation-to-RCE path
+
+## Output
+
+```markdown
+## Exploit Triage
+
+**Scope:** {diff / entry points reviewed}
+**Attacker model:** {remote unauth / authenticated untrusted}
+
+### Exploitable (reachable + impactful)
+- **{class}** {file}:{line}
+  - **Reach:** {how the attacker gets input to the sink}
+  - **Attack:** {the concrete request/payload}
+  - **Impact:** {what it grants}
+  - **Fix:** {the specific control}
+
+### Noted, not exploitable (unreachable or low impact)
+- {finding} — {why it does not pay}, one line each
+```

package/departments/dev/skills/ml-adoption-playbook/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: dev/ml-adoption-playbook
+description: >
+  Decides whether a problem needs ML at all, then adds it to a non-ML
+  codebase the cheap way — heuristic baseline first, a defined metric and
+  mistake budget, data readiness, and a decoupled seam before any model.
+  TRIGGER: "/dev ml-adoption-playbook", "should we use ML for this", "add
+  ML to", "is this an ML problem", "machine learning for X", "vale a pena
+  ML aqui?", "adicionar ML ao projeto", "modelo ou regras?". SKIP: the
+  model is already chosen and the job is to productionise it ->
+  dev/mle-workflow wins; a ranking/feed pipeline's plumbing ->
+  dev/rag-architect or dev/architecture-design wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# ML Adoption Playbook — `/dev ml-adoption-playbook`
+
+> **Agent:** Salvador (AI Engineering Specialist) | **Framework:** Heuristic-first, metric-and-mistake-budget, incremental adoption
+
+The most expensive way to add machine learning to a product is to reach
+for a model before asking whether rules would do. A regex, a threshold,
+or a lookup table ships in an afternoon, is trivial to debug, and is
+often within a few points of what a model would give — and if it is not,
+it becomes the baseline the model has to beat. This playbook decides
+whether the problem is really an ML problem, and if it is, adds ML to a
+codebase that has none of the scaffolding, one committed step at a time.
+
+## Phase 1 — Framing & feasibility (before any model)
+
+- **Heuristic check.** Could a rule, threshold, or lookup solve this
+  acceptably? If yes, ship that first — it is the baseline and often the
+  answer. A model that cannot beat a well-tuned heuristic is not worth
+  its operational cost.
+- **Metric.** Define how success is measured, tied to the product
+  decision — before touching data. No metric, no project.
+- **Mistake budget.** State what a wrong prediction costs and how many
+  are tolerable. This sets the bar the model must clear and whether a
+  human stays in the loop.
+- **Data reality.** Do labelled examples exist, or a path to them? Is the
+  outcome observable, and when? A problem with no labels and no path to
+  them is not yet an ML problem.
+
+## Phase 2 — Data readiness
+
+- Locate the data that would feed the model; assess volume, quality, and
+  bias before assuming it is usable.
+- Confirm the label is available at the time a prediction is needed, not
+  only in hindsight.
+
+## Phase 3 — Architectural seam
+
+- Add a decoupled boundary where the prediction plugs in — an interface
+  the current heuristic satisfies too, so the model can replace the rule
+  without rewiring the app.
+- Keep the heuristic as the fallback and the regression baseline.
+
+## Phase 4 — Baseline model
+
+- Integrate the simplest model that could work behind the seam; compare
+  it to the heuristic on the defined metric and mistake budget.
+- Promote only if it clears the bar. If it does not, the heuristic stays
+  and the finding is recorded — a negative result is still a result.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a request to "use ML" for something a threshold or lookup handles → propose the heuristic baseline first and the bar the model must beat
+- an ML plan with no defined metric or mistake budget → stop; those come before data
+- no labelled data and no path to it → this is not yet an ML problem; name what would make it one
+
+## Output
+
+```markdown
+## ML Adoption Assessment
+
+**Problem:** {what decision needs to be made}
+**Heuristic baseline:** {the rule that ships today, and how close it gets}
+**Verdict:** {ML justified? / heuristic suffices / not yet an ML problem}
+
+### If ML is justified
+- **Metric & bar:** {measure + threshold the model must beat the baseline by}
+- **Mistake budget:** {cost of a wrong call + human-in-loop or not}
+- **Data readiness:** {labels? volume? label latency?}
+- **Seam:** {the interface where the model plugs in, heuristic as fallback}
+```

package/departments/dev/skills/mle-workflow/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: dev/mle-workflow
+description: >
+  Turns model work into a production ML system — data contracts,
+  reproducible training, measurable eval gates, a deployable artifact,
+  and monitoring with a rollback path — using only the lanes the system
+  needs. TRIGGER: "/dev mle-workflow", "productionise this model", "ML
+  pipeline", "ranking/recommender/classifier/forecasting system", "model
+  refresh", "pôr o modelo em produção", "notebook para pipeline", "eval
+  gate do modelo". SKIP: RAG retrieval/context design -> dev/rag-architect
+  wins; the app/API around the model with no ML lifecycle concern ->
+  dev/architecture-design wins; prompt-injection/model-abuse threats ->
+  dev/ai-security wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# ML Engineering Workflow — `/dev mle-workflow`
+
+> **Agent:** Salvador (AI Engineering Specialist) | **Framework:** Data contracts, reproducible training, eval-gated promotion, monitored rollout
+
+A model in a notebook is a result; a model in production is a system that
+has to keep being right as the data underneath it moves. The gap between
+the two is not the algorithm — it is the plumbing that makes a prediction
+reproducible, gated on measured quality, deployable as an artifact, and
+observable once real traffic arrives. This workflow builds that plumbing,
+using only the lanes the system in front of you actually needs.
+
+## Scope calibration first
+
+Not every model has labels, online serving, a feature store, GPUs, or A/B
+tests. Pick the lanes that fit and make the missing ones explicit
+assumptions. A change that a data contract, a baseline, an eval script,
+and a rollback note would make reviewable does not need a feature store.
+
+## Lanes
+
+### 1. Data contract
+- Define the input schema, types, and allowed ranges; version it. A model is only as trustworthy as the guarantee on what reaches it.
+- Name the label source and its latency (is the outcome known now, or in 30 days?). Undelayed evaluation of a delayed-label problem is a lie.
+- Guard against **leakage**: a feature that encodes the target, or is computed with information unavailable at prediction time.
+
+### 2. Reproducible training
+- Pin the data snapshot, code version, dependency lockfile/environment, seed, and hyperparameters — a training run nobody can reproduce is not evidence.
+- Separate train/validation/test by the axis that matches production (time-based split for anything time-ordered, not random).
+- Emit a single versioned artifact (weights + preprocessing + the input schema it expects).
+
+### 3. Eval gate (promotion criteria)
+- State the metric and the threshold BEFORE training, tied to the decision the model drives — not accuracy for its own sake.
+- Evaluate on **slices**, not just the aggregate: a model that is 95% overall and 40% on the segment that matters is a failure.
+- Offline gate to promote; where traffic exists, an online check (shadow or canary) before full rollout.
+
+### 4. Deployable artifact & serving
+- The serving path must run the **same** preprocessing as training — train/serve skew is the most common silent production failure.
+- Batch vs online: choose by the freshness the decision needs, not by default.
+- Idempotent, versioned, with a health check.
+
+### 5. Monitoring & rollback
+- Watch input drift, prediction distribution, and — when labels arrive — realised quality against the offline estimate.
+- A **rollback path** to the previous artifact that can be triggered without a retrain.
+- Preserve every production failure (bad feature, stale label, artifact mismatch, drift) as a regression case.
+
+## Process
+
+1. Map the change onto the five lanes; mark which apply and which are explicit assumptions.
+2. Find the existing training/feature/serving/eval paths before adding a parallel ML stack (`git grep`, read them).
+3. Build the data contract and the eval gate first — they define what "done" means before any model work.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a feature computed from data unavailable at prediction time → the leakage, and the realistic offline score once it is removed
+- a random train/test split on time-ordered data → the optimistic metric it produces and the time-based split that fixes it
+- preprocessing written twice (once in training, once in serving) → the train/serve skew waiting to happen; share the code path
+
+## Output
+
+```markdown
+## ML Engineering Plan
+
+**System:** {what the model decides} · **Lanes in scope:** {of the five}
+**Explicit assumptions:** {labels / serving / traffic / monitoring owner}
+
+### Data contract
+{schema, label source + latency, leakage checks}
+
+### Training & eval gate
+{reproducibility pins, split axis, metric + threshold + slices}
+
+### Serving & monitoring
+{batch/online, skew guard, drift signals, rollback trigger}
+
+### Risks
+- {the failure mode} → {the guard}
+```

package/departments/dev/skills/safety-review/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: dev/safety-review
+description: >
+  Audits a change or an automation for destructive, irreversible
+  operations — bulk deletes, DROP/TRUNCATE, force pushes, mass emails,
+  raw disk or filesystem writes — and checks each has a guard: a scope
+  limit, a dry-run, a confirmation, a backup, a rollback. TRIGGER: "/dev
+  safety-review", "is this safe to run", "destructive operation", "will
+  this delete/overwrite", "review this migration/script/cron", "isto
+  apaga alguma coisa?", "revê este script destrutivo", "posso correr isto
+  em produção?"; run before shipping a migration, a bulk job, a cron, or
+  an autonomous automation. SKIP: exploitable-vulnerability review ->
+  dev/exploit-triage wins; general code review -> dev/code-review wins;
+  the deploy/rollout mechanics themselves -> dev/deploy wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# Safety Review — `/dev safety-review`
+
+> **Agent:** Bruno (Security Engineer) | **Framework:** Blast-radius analysis, reversibility, guard-before-execute
+
+The dangerous change is rarely the one that fails — it is the one that
+succeeds at the wrong scope. A migration that runs, a cleanup cron that
+fires, a bulk update that commits: each does exactly what it was told, to
+more rows or files or people than the author pictured. This pass finds
+the destructive and irreversible operations in a change or an automation
+and checks that every one is fenced — scoped, reversible, dry-runnable,
+or gated behind a confirmation — before it can run unattended.
+
+## What to flag
+
+| Operation | The guard it needs |
+|-----------|--------------------|
+| **Bulk delete / update** (`DELETE`/`UPDATE` without a tight `WHERE`, `deleteMany`, `rm -rf`) | An explicit scope, a row-count check, and a backup or soft-delete |
+| **Schema destruction** (`DROP`, `TRUNCATE`, a down-migration that loses data) | Reversibility or a snapshot; never irreversible without sign-off |
+| **Force / history rewrite** (`git push --force`, `reset --hard`, `filter-branch`) | Branch scoping; never on a shared branch |
+| **Mass outbound** (bulk email/notification/webhook) | A dry-run count, a rate limit, a test-recipient path |
+| **Raw disk / filesystem** (`dd`, recursive writes, `chmod -R`) | Path scoping and a confirmation |
+| **Unbounded loop / job** over production data | A limit, idempotency, and a resumable/rollback path |
+
+## Process
+
+1. Grep the change/automation for the destructive verbs — `DELETE`, `DROP`, `TRUNCATE`, `deleteMany`, `rm`, `--force`, `reset --hard`, bulk-send calls.
+2. For each, determine the **blast radius**: what is the maximum it can affect if a parameter is wrong or empty (an empty `WHERE` deletes the table; a null filter matches everything)?
+3. Check the guard is present and correct: scope, dry-run, confirmation, backup, rollback. A destructive op with no guard, or a guard that fails open, is a finding.
+4. Rank by reversibility — an irreversible op with no backup is critical; a scoped, reversible one is clean.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a `DELETE`/`UPDATE` whose `WHERE` could evaluate to empty or all-rows → the full-table blast radius and the scope/guard it needs
+- a down-migration or `DROP`/`TRUNCATE` with no snapshot → the irreversible data loss
+- an automation that runs unattended (cron, agent, CI job) touching production data with no dry-run or rollback → the guard to add before it ships
+
+## Output
+
+```markdown
+## Safety Review
+
+**Scope:** {change / automation reviewed}
+**Verdict:** {SAFE TO RUN / GUARDS REQUIRED}
+
+### Destructive operations
+- **{operation}** {file}:{line}
+  - **Blast radius:** {worst case if a parameter is wrong/empty}
+  - **Reversible?** {yes + how / no}
+  - **Guard present?** {scope/dry-run/confirmation/backup — or missing}
+  - **Fix:** {the guard to add before this runs}
+
+### Safe
+{operations already correctly fenced}
+```

package/departments/kb/skills/knowledge-ops/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: kb/knowledge-ops
+description: >
+  Writes a note to the Obsidian vault the evidence-first way and verifies
+  it landed — a note is not "saved" until it is read back, placed in the
+  right department path, linked with real `[[wikilinks]]`, and (when
+  indexed) confirmed searchable. TRIGGER: "/kb knowledge-ops", "save this
+  to the vault", "did the note land", "file this in Obsidian", "guarda
+  isto no vault", "confirma que a nota ficou", "indexa isto"; use when
+  capturing or reorganising knowledge that must be findable later, not
+  lost. SKIP: reading/answering from existing notes -> kb/search-kb wins;
+  a vault-wide freshness audit or broken-link sweep across existing notes
+  -> kb/knowledge-review wins; turning a source (video, PDF, article) into
+  structured notes -> kb/learn-content wins; planning a research effort ->
+  kb/research-plan wins.
+allowed-tools: [Read, Write, Edit, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# Knowledge Ops — `/kb knowledge-ops`
+
+> **Agent:** Clara (Knowledge Director) | **Framework:** Zettelkasten, evidence-flow, KB-first
+
+Saved means the vault can give it back. Not written-to-disk, not "the
+note is created" — retrievable: in the right department folder, with
+frontmatter that parses, with links that resolve, and picked up by the
+index that will be searched next month. Miss any one of those and the
+note is effort spent capturing knowledge that cannot be found the day it
+counts. Knowledge-ops holds every vault write to that acceptance test and
+does not call it done until the note has been read back and, when it must
+surface later, confirmed searchable.
+
+## Principles
+
+1. **Search before you write.** Query the vault first — a note that
+   duplicates an existing one should extend it, not fork it (KB-first,
+   `arka/SKILL.md`).
+2. **Right path, valid frontmatter.** File under the correct department
+   MOC with parseable YAML frontmatter; a note in the wrong place is a
+   note lost.
+3. **Links must resolve.** Every `[[wikilink]]` points at a note that
+   exists (or is deliberately a forward reference you will create); a
+   dead link is a broken trail, not a decoration.
+4. **Read it back.** After writing, read the note — confirm the content,
+   frontmatter, and links are as intended, not as assumed.
+5. **Confirm findable.** When the note must be retrievable, index it and
+   verify a search returns it. "Saved" means "the vault can return it."
+
+## Process
+
+1. Search the vault for the topic; decide extend-vs-create.
+2. Write or patch the note in the right department path, with frontmatter
+   and resolving `[[wikilinks]]`.
+3. Read the note back and check content, frontmatter, and every link.
+4. If retrieval matters, index and confirm a search surfaces it.
+5. Report what landed, where, and how it was verified.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a note written with no `[[wikilinks]]` → the orphan it becomes, and the neighbours to link
+- a `[[link]]` whose target note does not exist → the dead trail, and whether to create the target or fix the link
+- knowledge captured but never indexed when it will be searched for later → the index step that makes it findable
+
+## Output
+
+```markdown
+## Knowledge Ops
+
+**Captured:** {what was written / reorganised}
+**Location:** {department path + note title}
+
+### Verified
+- frontmatter: {parsed OK}
+- links: {N wikilinks, all resolve}
+- read-back: {confirmed}
+- searchable: {index confirmed / n/a}
+
+**Verdict:** {SAVED and findable / INCOMPLETE — what still needs fixing}
+```

package/departments/ops/skills/github-ops/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ops/github-ops
+description: >
+  Drives git and GitHub operations under the branch-isolation and
+  evidence rules — isolated branch, staging by explicit path, a PR whose
+  CI is proven CLEAN before any merge, and a verified push — never a merge
+  on a still-pending check. TRIGGER: "/ops github-ops", "open a PR",
+  "merge when green", "is this safe to merge", "abre um PR", "faz merge
+  quando o CI passar", "cria a branch e o PR", "confirma os checks"; use
+  for the branch → commit → PR → merge lifecycle of a change. SKIP: the
+  version-bump/tag/npm-publish release pipeline -> dev/release wins; a
+  CI/CD deploy to infrastructure -> dev/deploy wins; running arbitrary
+  non-git shell steps -> ops/terminal-ops wins.
+allowed-tools: [Bash, Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# GitHub Ops — `/ops github-ops`
+
+> **Agent:** Daniel (Ops Lead) | **Framework:** Branch-isolation (NON-NEGOTIABLE), evidence-flow, merge-on-green
+
+"I opened the PR" and "the PR is mergeable with every check green" are
+not the same sentence, and treating them as one is how a red build lands
+on the default branch. A merge fired while CI was still `pending`, a
+`git add -A` that swept an unrelated file into the commit, a force-push
+that quietly rewrote a teammate's history — each is a git operation that
+*ran* without being *verified*. This skill drives the branch → commit →
+PR → merge lifecycle so that every step is isolated and proven: staged by
+explicit path, pushed and confirmed, and merged only once `gh pr checks`
+reads CLEAN.
+
+## Rules
+
+1. **Branch-isolation, always.** Never commit to the default branch. Cut
+   a feature branch first; the change lives and dies on it (constitution
+   `branch-isolation`, NON-NEGOTIABLE).
+2. **Stage by explicit path.** `git add <path>` for what belongs in the
+   commit — never `git add -A`/`.` blindly. Verify with `git status` and
+   `git diff --cached` before committing; a parallel agent's file must
+   not leak in.
+3. **Merge only on proven green.** After opening the PR, poll
+   `gh pr checks <n>` until zero `pending` and zero failures, and
+   `mergeStateStatus` is `CLEAN`. A merge on a pending check is a defect,
+   not a shortcut.
+4. **Force-push is scoped and lease-guarded.** Only after a deliberate
+   rebase, only `--force-with-lease`, never on a shared branch.
+5. **Verify the push landed.** Read the ref update line; don't assume.
+
+## Process
+
+1. Confirm the current branch. On the default branch → create the feature
+   branch before touching anything.
+2. Stage by path, review `git diff --cached`, commit with a conventional
+   message.
+3. Push and read the ref-update confirmation.
+4. Open the PR; then poll `gh pr checks` to completion.
+5. Merge only when checks are CLEAN; confirm the merge and sync the
+   default branch.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a commit staged with `git add -A`/`.` → the explicit-path staging and the `git diff --cached` check that prevents a leak
+- a merge requested while `gh pr checks` still shows `pending` → wait-for-green before the merge, with the check status quoted
+- a `git push --force` without `--force-with-lease` on a branch others may hold → the lease-guarded form, or don't
+
+## Output
+
+```markdown
+## GitHub Ops
+
+**Change:** {what the branch carries}
+**Branch:** {feature branch, off default}
+
+### Steps (with evidence)
+- staged: {paths} — `git diff --cached` reviewed
+- pushed: {ref-update line}
+- PR: #{n} — checks {CLEAN / list of pending→pass}
+
+**Verdict:** {MERGED after green, confirmed / HELD — checks not yet CLEAN}
+```

package/departments/ops/skills/terminal-ops/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: ops/terminal-ops
+description: >
+  Runs shell operations the evidence-first way — every command's exit
+  code and real output are captured and checked before anything is
+  reported as done, and a non-zero exit stops the chain instead of being
+  narrated over. TRIGGER: "/ops terminal-ops", "run this safely",
+  "execute and verify", "did this command actually work", "corre isto e
+  confirma", "verifica o exit code", "isto correu mesmo?"; use when a task
+  hangs on a sequence of shell commands whose success must be proven, not
+  assumed. SKIP: git/GitHub-specific flows (branch, PR, merge-on-green) ->
+  ops/github-ops wins; a CI/CD deployment pipeline -> dev/deploy wins;
+  documenting the procedure instead of running it -> ops/sop-create wins.
+allowed-tools: [Bash, Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# Terminal Ops — `/ops terminal-ops`
+
+> **Agent:** Daniel (Ops Lead) | **Framework:** Evidence-flow G3, fail-fast, exit-code-as-truth
+
+The deploy script exits 0. One line up sits `Error: connection refused`
+— but a wrapper swallowed the real status and handed back the echo, so
+the pipeline read green and shipped a half-applied migration. No one
+lied; the output simply never got checked against the exit code, and the
+exit code never got checked at all. Terminal-ops runs shell work under a
+single rule: the status is the verdict and the output is only a hint
+toward it. Anything that matters has its exit code captured and read
+against a success signal named in advance, and a non-zero exit halts the
+sequence rather than scrolling past.
+
+## Principles
+
+1. **Exit code is the truth, output is a hint.** `echo $?` (or the tool's
+   own status) after anything that matters. A zero exit with an empty
+   result is still a result to inspect; a non-zero exit is a stop.
+2. **Chain on success, never on hope.** Sequence with `&&` or an explicit
+   status check between steps, so step 2 cannot run on step 1's failure.
+3. **Capture, then read.** Redirect output you need to judge (`2>&1`),
+   read it, and quote the line that proves the claim — never report "done"
+   from memory of what the command *should* do.
+4. **Least surprise on destructive verbs.** Before `rm`/`mv`/`>`
+   overwrites, confirm scope (what it matches) — hand off to
+   `ops/github-ops` for history rewrites and `dev/db-design` for schema.
+
+## Process
+
+1. State the goal and the **success signal** in advance — the exact exit
+   code, file, or output that will prove it.
+2. Run the command, capturing status and the output you need to judge.
+3. Read the result against the success signal. Match → proceed. Mismatch
+   → stop, surface the real error line, do not continue the chain.
+4. Report with the evidence: the command, its exit code, and the line
+   that confirms it.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a multi-step sequence where a later step assumes an earlier one passed → the status check to insert between them
+- a command whose success was reported from its output text, not its exit code → the `$?`/status check that actually proves it
+- a destructive command (`rm -rf`, `>`, `truncate`) with an unbounded or unchecked target → the scope confirmation before it runs
+
+## Output
+
+```markdown
+## Terminal Ops
+
+**Goal:** {what the sequence had to achieve}
+**Success signal:** {the exit code / file / output line that proves it}
+
+### Executed
+- `{command}` → exit {code} — {the line that confirms or refutes}
+
+**Verdict:** {DONE, proven by evidence above / STOPPED at step N — real error}
+```

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "4.19.0",
+    "version": "4.21.0",
     "marketplace": "arkaos"
   },
   "structural": {
@@ -1095,6 +1095,19 @@
         "origin": "arkaos"
       }
     },
+    "exploit-triage": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "extract-data": {
       "depts": [
         "strategy"
@@ -1217,6 +1230,19 @@
         "origin": "arkaos"
       }
     },
+    "github-ops": {
+      "depts": [
+        "ops"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-ops@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "growth-loop": {
       "depts": [
         "marketing"
@@ -1412,6 +1438,19 @@
         "origin": "arkaos"
       }
     },
+    "knowledge-ops": {
+      "depts": [
+        "kb"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-kb@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "knowledge-review": {
       "depts": [
         "kb"
@@ -1633,6 +1672,32 @@
         "origin": "arkaos"
       }
     },
+    "ml-adoption-playbook": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
+    "mle-workflow": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "moat-analysis": {
       "depts": [
         "strategy"
@@ -2475,6 +2540,19 @@
         "origin": "arkaos"
       }
     },
+    "safety-review": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "scaffold": {
       "depts": [
         "dev"
@@ -2875,6 +2953,19 @@
         "origin": "arkaos"
       }
     },
+    "terminal-ops": {
+      "depts": [
+        "ops"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-ops@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "thumbnail-package": {
       "depts": [
         "content"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.19.0"
+version = "4.21.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}