arkaos 4.20.0 → 4.21.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-86 agents. 17 departments. 287 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.20.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. 287 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/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.20.0",
+    "version": "4.21.0",
     "marketplace": "arkaos"
   },
   "structural": {
@@ -1230,6 +1230,19 @@
         "origin": "arkaos"
       }
     },
+    "github-ops": {
+      "depts": [
+        "ops"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-ops@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "growth-loop": {
       "depts": [
         "marketing"
@@ -1425,6 +1438,19 @@
         "origin": "arkaos"
       }
     },
+    "knowledge-ops": {
+      "depts": [
+        "kb"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-kb@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "knowledge-review": {
       "depts": [
         "kb"
@@ -2927,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.20.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.20.0"
+version = "4.21.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}