arkaos 5.1.1 → 5.3.0

package/CONSTITUTION.md

@@ -115,7 +115,7 @@ Level re-tiering requires explicit operator approval and a recorded
 ## Compressed Context (Synapse L0)
 
 ```
-[Constitution] NON-NEGOTIABLE: branch-isolation, security-gate, mandatory-qa, evidence-flow, arkaos-not-yes-man, excellence-mandate | QUALITY-GATE: marta-cqo, eduardo-copy, francisca-tech-ux | MUST (28) incl.: squad-routing, spec-driven, conventional-commits, test-coverage, subagent-discipline, persona-vs-artifact
+[Constitution] NON-NEGOTIABLE: branch-isolation, security-gate, mandatory-qa, evidence-flow, arkaos-not-yes-man, excellence-mandate | QUALITY-GATE: marta-cqo, eduardo-copy, francisca-tech-ux | MUST (29) incl.: squad-routing, spec-driven, conventional-commits, test-coverage, subagent-discipline, persona-vs-artifact
 ```
 
 ---

package/README.md

@@ -1,5 +1,7 @@
 # ArkaOS
 
+<img src="assets/github-social.png" alt="ArkaOS — The Operating System for AI Agent Teams" width="100%">
+
 **The Operating System for AI Agent Teams.**
 
 89 agents. 17 departments. 333 skills. Enterprise frameworks. Multi-runtime. One install.
@@ -8,7 +10,7 @@
 npx arkaos install
 ```
 
-[![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-4500%2B%20passing-brightgreen)]()
+[![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![npm](https://img.shields.io/npm/dw/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-4500%2B%20passing-brightgreen)]()
 
 > All counts in this document are generated by `python scripts/tools/docs_stats.py`
 > and locked by a test — they cannot drift from the repository.

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.1.1 — 89 agents, 17 departments, 333 skills, 298 commands, 19 ADRs.
+> v5.3.0 — 89 agents, 17 departments, 333 skills, 299 commands, 20 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is
@@ -41,7 +41,7 @@ answers as a generic assistant.
 | `/brand` | 12 |
 | `/community` | 15 |
 | `/content` | 20 |
-| `/dev` | 36 |
+| `/dev` | 37 |
 | `/do` | 1 |
 | `/ecom` | 18 |
 | `/fin` | 10 |

package/VERSION

@@ -1 +1 @@
-5.1.1
+5.3.0

package/arka/SKILL.md

@@ -22,6 +22,22 @@ external research (Context7, WebSearch, WebFetch, Firecrawl):
    explicitly declare a KB gap.
 4. Only after (1)–(3) may external tools run.
 
+**Which external tool, for code questions.** Once the KB step is done, two
+externals answer different questions and neither substitutes for the other:
+
+| Tool | Answers | Reach for it when |
+| --- | --- | --- |
+| `mcp__context7__query-docs` | the contract — what the official docs say | you need documented signatures, config keys, version changes |
+| `mcp__gh-grep__searchGitHub` | the practice — how N public repos really implement it | you need real call-sites, idioms, migration patterns, or an error signature seen in the wild |
+
+Adopting an unfamiliar API wants both: the contract, then the practice.
+`gh-grep` is **literal grep with regex over public repos** — query it with
+code tokens (`createBrowserRouter`, `defineConfig({`), never with a natural
+language sentence, and filter by language or path. What it returns is a
+prior about practice, not ground truth: confirm against the docs before
+adopting. It cannot see private code (use the KB or codebase-memory) and it
+is the wrong tool for non-code topics (use WebSearch/Firecrawl).
+
 **Fail-open:** Graphify runs on a per-user endpoint (home LAN, localhost,
 or VPS — see `knowledge.graphify` config). When it is not configured or
 not reachable, treat it as a gap and proceed with Obsidian alone; never
@@ -75,7 +91,7 @@ ends with a single line:
 | Field | Meaning | Allowed values |
 | --- | --- | --- |
 | `kb=N` | Number of Obsidian / KB notes consulted | integer ≥ 0 |
-| `research=X` | MCPs invoked (or 'none') | `none` or comma-list: `perplexity,exa,context7,firecrawl,xmcp` |
+| `research=X` | MCPs invoked (or 'none') | `none` or comma-list: `perplexity,exa,context7,ghgrep,firecrawl,xmcp` |
 | `persona=Y` | Conclave / squad-lead persona who drove the response | `Tomas`, `Marco`, `Marta`, `Eduardo`, `Francisca`, `Paulo`, `Iris`, etc., or `orchestrator` |
 | `gap=Z` | KB gap topic when external research filled a missing area | `none` or short topic slug |
 | `critic=W` | Self-critic verdict | `passed` \| `failed` \| `skipped` |

package/arka/skills/comfyui/SKILL.md

@@ -82,7 +82,7 @@ The Forge for multi-agent planning before execution.
 - Phase 0.5: Forge analysis (after spec creation, before squad planning)
 - Complexity assessment: automatic via Synapse L8 (ForgeContextLayer)
 - Manual invocation: `/forge` command
-- Handoff: Forge outputs structured plan -> squad executes phases
+- Handoff: Forge outputs structured plan → squad executes phases
 <!-- arka:feature:forge-integration:end -->
 
 <!-- arka:feature:quality-gate:start -->
@@ -115,7 +115,7 @@ Three workflow tiers based on task complexity:
 | Tier | Phases | When |
 |------|--------|------|
 | Enterprise | 7-10 phases | Complex features, multi-file changes |
-| Focused | 3-5 phases | Medium tasks, single-domain changes |
+| Focused | 3-4 phases | Medium tasks, single-domain changes |
 | Specialist | 1-2 phases | Simple tasks, quick fixes |
 
 Tier selection is automatic based on complexity assessment.

package/config/constitution.yaml

@@ -205,7 +205,7 @@ enforcement_levels:
     description: "Best practices. Encouraged but not enforced."
     rules:
       - id: research-first
-        rule: "Research before building. Check Context7, existing solutions, and prior art."
+        rule: "Research before building. Check Context7 for the documented contract, gh-grep for how public code really implements it, the KB for what we already decided, and existing solutions and prior art wherever they live — papers, standards, and closed-source products included."
 
       - id: self-critique
         rule: "Every implementation should include a self-critique phase"
@@ -243,7 +243,7 @@ enforcement_levels:
         enforcement: "Critic-pass-per-phase mandatory; sycophancy detector rejects 'tens razão' / 'OK doing what you say' responses without pushback; reviewer dispatch is sub-fragmented with checkpoints rather than monolithic execution."
 
       - id: always-research
-        rule: "Every substantive task consults the Client KB FIRST (Obsidian vault + memory files + project descriptors), then relevant Personas, then Context MCPs (Context7, Perplexity, Exa, Firecrawl, XMCP) for gaps. No exceptions, including mechanical edits — the KB lookup is cheap and the cost of missing context is paid by the user."
+        rule: "Every substantive task consults the Client KB FIRST (Obsidian vault + memory files + project descriptors), then relevant Personas, then Context MCPs (Context7 for documented contracts, gh-grep for how public repos really implement it, Perplexity, Exa, Firecrawl, XMCP) for gaps. No exceptions, including mechanical edits — the KB lookup is cheap and the cost of missing context is paid by the user."
         enforcement: "[arka:meta] transparency line lists kb=N research=X persona=Y on every substantive response; absence is treated as work-not-done. Hierarchy: Client KB > Personas > Context MCPs."
 
       - id: inter-agent-checkpoints

package/core/governance/evidence_checks.py

@@ -27,6 +27,7 @@ import configparser
 import fnmatch
 import importlib.util
 import json
+import os
 import re
 import shlex
 import shutil
@@ -165,6 +166,24 @@ def _skip(check: str, reason: str) -> CheckResult:
     )
 
 
+def _expand_argv(argv: list[str]) -> list[str]:
+    """Expand `~` where it means a path; shlex.split leaves it literal.
+
+    argv[0] is always a program path, so both `~/` and `~user` expand
+    there. Later tokens expand only in the `~/` form: a bare `~word` is
+    far more likely to be a filter expression (`pytest -k ~root`) than a
+    home directory, and rewriting it would silently change what runs.
+    """
+    if not argv:
+        return argv
+    head = os.path.expanduser(argv[0]) if argv[0].startswith("~") else argv[0]
+    tail = [
+        os.path.expanduser(tok) if tok.startswith("~/") else tok
+        for tok in argv[1:]
+    ]
+    return [head, *tail]
+
+
 def _run(
     check: str, cmd: list[str], project_dir: Path, timeout: int,
 ) -> CheckResult:
@@ -177,6 +196,15 @@ def _run(
         )
     except FileNotFoundError:
         return _skip(check, f"tool not found: {cmd[0]}")
+    except OSError as exc:
+        # Anything else exec can refuse — a directory, a non-executable
+        # file, a broken symlink. The gate must report, never raise: an
+        # uncaught error here produces no EvidenceReport at all, which is
+        # worse than the silent skip this module works to avoid.
+        return CheckResult(
+            check=check, ran=True, passed=False, command=command_str,
+            exit_code=None, summary=f"cannot execute {cmd[0]}: {exc.strerror}",
+        )
     except subprocess.TimeoutExpired:
         # subprocess.run kills the child on expiry before raising.
         return CheckResult(
@@ -323,6 +351,12 @@ def _check_lint(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
+    if changed is not None and not changed:
+        # A KNOWN-empty diff must not inherit the project-wide baseline:
+        # a zero-write deliverable was gated on master's pre-existing
+        # ruff debt (QG 2026-08-04). None still means "scope unknown"
+        # and keeps the project-wide run.
+        return _skip("lint", "no changed files (empty diff)")
     if changed:
         scoped = _lint_scoped(project_dir, changed, timeout)
         if scoped is not None:
@@ -371,6 +405,11 @@ def _check_typecheck(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
+    if changed is not None and not changed:
+        # Same zero-diff contract as lint: mypy/tsc run project-wide and
+        # never read the diff, so a known-empty diff would inherit
+        # master's type debt the moment tooling is configured.
+        return _skip("typecheck", "no changed files (empty diff)")
     if _mypy_configured(project_dir) and shutil.which("mypy"):
         return _run("typecheck", ["mypy", "."], project_dir, timeout)
     if (project_dir / "tsconfig.json").is_file():
@@ -431,21 +470,38 @@ def _degrade_pytest_no_tests(result: CheckResult) -> CheckResult:
     return replace(result, passed=None, summary=prefix + result.summary)
 
 
+def _run_pinned_tests(
+    test_command: str, project_dir: Path, timeout: int,
+) -> CheckResult:
+    """Run the operator's pinned --test-command. Never skips."""
+    argv = _expand_argv(shlex.split(test_command))
+    result = _run("tests", argv, project_dir, timeout)
+    if not result.ran:
+        # A command the operator pinned explicitly is not optional.
+        # _run reports an unresolvable binary as ran=False, which an
+        # aggregator reads as "not applicable" — so a typo in the
+        # path would let a PR through on a suite that never ran.
+        return CheckResult(
+            check="tests", ran=True, passed=False,
+            command=" ".join(argv), exit_code=None,
+            summary=f"pinned --test-command could not run: {result.summary}",
+        )
+    # exit 5 is pytest's "no tests collected"; scan the first 3
+    # tokens so `python -m pytest` / `arka-py -m pytest` degrade too,
+    # while non-pytest runners (npm test) stay a real FAIL. Bounded to
+    # argv[:3] so a later test-path arg named *pytest* never matches
+    # (issue #354).
+    if any("pytest" in Path(tok).name for tok in argv[:3]):
+        return _degrade_pytest_no_tests(result)
+    return result
+
+
 def _check_tests(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
     if test_command:
-        argv = shlex.split(test_command)
-        result = _run("tests", argv, project_dir, timeout)
-        # exit 5 is pytest's "no tests collected"; scan the first 3
-        # tokens so `python -m pytest` / `arka-py -m pytest` degrade too,
-        # while non-pytest runners (npm test) stay a real FAIL. Bounded to
-        # argv[:3] so a later test-path arg named *pytest* never matches
-        # (issue #354).
-        if any("pytest" in Path(tok).name for tok in argv[:3]):
-            return _degrade_pytest_no_tests(result)
-        return result
+        return _run_pinned_tests(test_command, project_dir, timeout)
     if _has_python(project_dir, changed):
         local_pytest = _project_pytest(project_dir)
         if local_pytest:
@@ -1024,8 +1080,10 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def _csv(value: str | None) -> list[str] | None:
-    if not value:
+    if value is None:
         return None
+    # `--changed-files ""` is a KNOWN-empty diff and maps to [] so the
+    # zero-diff skip fires; an omitted flag stays None (scope unknown).
     return [item.strip() for item in value.split(",") if item.strip()]
 
 

package/core/hooks/session_start.py

@@ -96,7 +96,7 @@ _META_TAG_CONTRACT = (
     "\n\n[ARKA:META-TAG] Every substantive response ends with a single line:"
     "\n  [arka:meta] kb=N research=X persona=Y gap=Z critic=W"
     "\nFields: kb=N (Obsidian/KB notes consulted), research=X (MCPs invoked:"
-    " perplexity,exa,context7,firecrawl,xmcp or 'none'), persona=Y (advisor"
+    " perplexity,exa,context7,ghgrep,firecrawl,xmcp or 'none'), persona=Y (advisor"
     " name or 'orchestrator'), gap=Z (KB gap topic or 'none'), critic=W"
     " (passed|failed|skipped)."
     "\nMandatory after: EFFECT tool calls, plan/recommendation outputs, QG"

package/core/sync/features/forge.yaml

@@ -2,7 +2,7 @@ name: forge-integration
 added_in: "2.14.0"
 mandatory: true
 section_title: "Forge Integration"
-detection_pattern: "arka:feature:forge-integration|## Forge Integration|arka-forge"
+detection_pattern: "arka:feature:forge-integration|## Forge Integration|arka-forge(?![\\w-])"
 deprecated_in: null
 content: |
   <!-- arka:feature:forge-integration:start -->

package/core/sync/features/spec-gate.yaml

@@ -2,7 +2,7 @@ name: spec-driven-gate
 added_in: "2.13.0"
 mandatory: true
 section_title: "Spec-Driven Development"
-detection_pattern: "arka:feature:spec-driven-gate|## Spec-Driven Development|arka-spec"
+detection_pattern: "arka:feature:spec-driven-gate|## Spec-Driven Development|arka-spec(?![\\w-])"
 deprecated_in: null
 content: |
   <!-- arka:feature:spec-driven-gate:start -->

package/core/sync/features/workflow-tiers.yaml

@@ -13,7 +13,7 @@ content: |
   | Tier | Phases | When |
   |------|--------|------|
   | Enterprise | 7-10 phases | Complex features, multi-file changes |
-  | Focused | 3-5 phases | Medium tasks, single-domain changes |
+  | Focused | 3-4 phases | Medium tasks, single-domain changes |
   | Specialist | 1-2 phases | Simple tasks, quick fixes |
 
   Tier selection is automatic based on complexity assessment.

package/departments/brand/SKILL.md

@@ -2,7 +2,7 @@
 name: arka-brand
 description: >
   Brand & Design department. Full brand identity creation, UX/UI design, design systems,
-  visual identity, and brand strategy. 4-agent team applying Primal Branding, StoryBrand,
+  visual identity, and brand strategy. 10-agent team applying Primal Branding, StoryBrand,
   12 Archetypes, Nielsen Heuristics, Atomic Design, and Dieter Rams principles.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---

package/departments/dev/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: arka-dev
 description: >
-  Full-stack development department. Enterprise-grade 9-agent team with structured
+  Full-stack development department. Enterprise-grade 15-agent team with structured
   multi-phase workflows. Implements features, APIs, reviews code, manages architecture,
   security audits, CI/CD, database design, and AI-assisted development.
   Frameworks: Clean Architecture, DDD, TDD, DORA Metrics, OWASP Top 10.
@@ -37,6 +37,7 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | `/dev performance <target>` | Performance audit (CWV, API latency, DB) | Focused |
 | `/dev pipeline <project>` | CI/CD pipeline design and setup | Focused |
 | `/dev clean-review <file>` | Clean Code + SOLID compliance review | Specialist |
+| `/dev research <topic>` | Library evaluation and pattern discovery (KB + Context7 + gh-grep + web) | Specialist |
 | `/dev spec <description>` | Create feature specification (mandatory pre-impl) | Specialist |
 | `/dev scaffold <type> <name>` | Project scaffolding from starter repos | Specialist |
 | `/dev do <description>` | Smart routing to the right dev command | Orchestrator |
@@ -81,6 +82,30 @@ Diagnose step: `get_architecture` for the structural map,
 PRIOR, not ground truth: verify with Read before editing. When the MCP
 is absent the phases run as before (Grep/Read exploration).
 
+## Real-world grounding (gh-grep MCP)
+
+`codebase-memory` answers "how does OUR code do this". When the question
+is "how does anyone do this", call `mcp__gh-grep__searchGitHub` — literal
+grep with regex over public repositories — in Phase 1 RESEARCH and in
+Diagnose, whenever an external API, library idiom, or error signature is
+unfamiliar or disputed.
+
+Query it with **code tokens**: `useSyncExternalStore`, `from
+sqlalchemy.orm import`, `Cannot read properties of undefined`. Filter by
+language and path. A natural-language sentence returns noise, so a first
+attempt that phrases the question in prose will look like the tool failing
+when it is the query that failed.
+
+Pair it with Context7, which answers the complementary question: Context7
+gives the documented contract; gh-grep gives the practice N teams actually
+shipped. Where they disagree, the docs win and the divergence itself is
+worth reporting. Treat results as a prior about practice — they carry no
+authority over our own code, which you still read directly.
+
+Skip it for private code (it indexes public repositories only — use
+`codebase-memory` or the KB), for documentation lookups (Context7), and for
+anything that is not code (WebSearch, Firecrawl).
+
 ## Focused Workflow (4 Phases)
 
 For `/dev debug`, `/dev refactor`, `/dev db`, `/dev performance`, `/dev pipeline`: Diagnose → Implement with tests → Rita validates → Quality Gate (Marta).

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

@@ -85,6 +85,11 @@ allowed-tools: [Read, Bash, Grep, Glob, Agent]
 - [ ] Assume every variable could be null/undefined
 - [ ] Assume every external call will fail
 - [ ] Ask: "If I deleted this change, what would break?"
+- [ ] For an abuse vector that depends on how a third-party library
+      behaves, confirm the behaviour with `mcp__gh-grep__searchGitHub`
+      (real call-sites) plus Context7 (documented contract) before
+      raising it as CRITICAL — a hostile persona that invents the
+      library's behaviour is refuting itself, not the code
 
 ## Verdicts
 

package/departments/dev/skills/api-design/SKILL.md

@@ -28,6 +28,14 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 7. **Consistent response** — `{ "data": ..., "meta": { "pagination": ... } }`
 8. **Error format** — `{ "error": { "code": "VALIDATION_FAILED", "message": "...", "details": [...] } }`
 
+When the contract has to interoperate with something you do not control — a
+partner API, an SDK's expectations, a webhook consumer — check the shape
+that already exists in the wild. `mcp__gh-grep__searchGitHub` on the field
+names or the header (`X-Idempotency-Key`, `"cursor":`) shows what clients
+are already written against. Matching an established shape costs nothing
+and removes a whole class of integration surprise; diverging from one is a
+decision that belongs in the ADR with its reason.
+
 ## Output: OpenAPI Snippet
 
 ```yaml

package/departments/dev/skills/architecture-design/SKILL.md

@@ -35,6 +35,12 @@ allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, WebFetch]
 - Ask user: What system/feature needs architecture?
 - Clarify: Scale requirements, team size, tech constraints
 - Identify: Domain boundaries, data flows, external integrations
+- Where the design leans on a specific framework or infrastructure
+  primitive, check the precedent with `mcp__gh-grep__searchGitHub`: grep
+  the structural tokens (a config key, a base class, a directory
+  convention) and read how real systems wired it. Feed what you find into
+  Step 4's Alternatives Considered — a pattern that public repos abandoned
+  is an alternative you can rule out with evidence instead of taste.
 
 ### Step 3: Architecture Design
 Apply the appropriate pattern:

package/departments/dev/skills/build-fix/SKILL.md

@@ -46,9 +46,15 @@ reinstall the world) before reading what the tool actually said.
    | Code | type error, syntax error, failed macro/codegen |
    | Toolchain | wrong runtime version, missing system binary |
    | Cache | passes clean, fails incrementally (or the reverse) |
-4. **Fix the root, not the symptom.** A cast that silences a type error
+4. **When the signature is unfamiliar, search it.** Paste the literal
+   error string into `mcp__gh-grep__searchGitHub` (strip the paths and
+   line numbers, keep the message). Repos that hit the same signature
+   often carry the fix in the surrounding config or lockfile, and the
+   search shows which fixes were adopted rather than merely proposed —
+   frequently faster than reading the issue tracker.
+5. **Fix the root, not the symptom.** A cast that silences a type error
    the compiler was right about is a deferred production bug.
-5. **Prove it.** Two consecutive clean builds — one incremental, one
+6. **Prove it.** Two consecutive clean builds — one incremental, one
    from clean — with exit codes on record. One green build after a
    cache clear proves nothing about the fix.
 

package/departments/dev/skills/clean-code-review/SKILL.md

@@ -47,6 +47,14 @@ report with issues categorized as BLOCKER, WARNING, or NOTE.
 - [ ] **No business logic in controllers** — Controllers delegate to services
 - [ ] **Repository pattern** — Data access abstracted from business logic
 
+### Idiom disputes
+
+"This is not the idiomatic way to use X" is a claim about a community, and
+it needs evidence before it becomes a blocker. Grep the symbol with
+`mcp__gh-grep__searchGitHub` and let the call-sites settle it. If real repos
+split evenly between two forms, downgrade the finding to a NOTE about
+staying consistent inside our own codebase.
+
 ## Output Format
 
 ```markdown

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

@@ -28,6 +28,20 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 
 Code review against Clean Code and SOLID. Checks naming, SRP, DIP, test coverage, security.
 
+## Before you call it a BLOCKER
+
+When the finding rests on a claim about a third-party API — "this hook must
+not run in an effect", "that option is ignored here" — and you are not
+certain, verify it before writing it down. `mcp__gh-grep__searchGitHub` on
+the literal symbol shows how the API is used across public repos; Context7
+shows what its maintainer documents. A blocker that turns out to describe
+the reviewer's assumption rather than the library's behaviour costs the
+author a cycle and costs the review its authority.
+
+Run this check only when a claim about someone else's library is in
+dispute. Findings about our own code — naming, SRP, coupling, coverage —
+are settled by reading the code in front of you.
+
 ## Output
 
 Review report: BLOCKER/WARNING/NOTE with line references and fix suggestions

package/departments/dev/skills/dependency-audit/SKILL.md

@@ -68,6 +68,14 @@ Run these per ecosystem:
 | Major (1.2.3 -> 2.0.0) | High | Read migration guide, plan sprint work |
 | Deprecated | Critical | Find replacement, schedule migration |
 
+Registry download counts measure installs, not health: CI runs, mirrors,
+proxies, and bots inflate them, while a vendored dependency is fetched once
+and committed, after which it stops counting altogether even though the
+project still depends on it. For a dependency you suspect is abandoned or
+about to be, check real usage with `mcp__gh-grep__searchGitHub`: grep its
+import path and read whether recent code still calls it, or only wraps it in
+a shim on the way out.
+
 ## Supply Chain Checks
 
 - [ ] Lock files committed and up to date

package/departments/dev/skills/refactor-plan/SKILL.md

@@ -34,6 +34,13 @@ analysis), `search_graph` to find duplicated implementations worth
 consolidating. The graph is a prior — verify with Read before planning
 an edit.
 
+When the refactor moves toward an unfamiliar shape — splitting a service,
+adopting a new boundary, restructuring around a library's expected layout —
+look at how public repos structure the same thing before committing to it.
+`mcp__gh-grep__searchGitHub` on the framework's structural tokens shows the
+layouts that survived contact with real teams. Precedent is an argument, not
+an authority: our constraints still decide.
+
 ## Output
 
 Refactoring plan with patterns, risk assessment, and test verification steps

package/departments/dev/skills/research/SKILL.md

@@ -3,14 +3,16 @@ name: dev/research
 description: >
   Dev-scoped technical research (Lucas, Analyst): library evaluation,
   framework/package selection, code pattern comparison, and engineering
-  best-practice discovery via Context7 official docs + web research,
-  ending in a trade-off report with a recommendation.
+  best-practice discovery grounded in the KB first, then Context7 for the
+  documented contract, gh-grep for how public repos really implement it,
+  and web research — ending in a trade-off report with a recommendation.
   TRIGGER: user types "/dev research", "avalia a biblioteca", "que
   lib/framework usamos", "compara X vs Y" for code dependencies,
   "library evaluation", "which package/ORM/framework should we use",
-  "best practice" questions about implementation choices — load BEFORE
-  adding a new dependency or committing to an architecture-relevant
-  library.
+  "best practice" questions about implementation choices, and real-world
+  usage lookups ("exemplos reais", "prior art", "como implementam os
+  outros", "how do others use this API") — load BEFORE adding a new
+  dependency or committing to an architecture-relevant library.
   SKIP: general, market, or knowledge-base research whose deliverable
   is an Obsidian KB note, including "best practices for" a non-code
   topic — arka-research (/arka research, 5-source fan-out) wins;
@@ -27,12 +29,56 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 
 # Research — `/dev research <topic>`
 
-> **Agent:** Lucas (Analyst) | **Framework:** Context7 + Web Research
+> **Agent:** Lucas (Analyst) | **Framework:** KB-first + Context7 + gh-grep + Web Research
 
 ## What It Does
 
 Research a technical topic: library evaluation, pattern comparison, best practice discovery.
 
+## Sources, and the question each one answers
+
+Work through all four before writing a recommendation. Each answers
+something the others cannot, and a report built on one of them is a report
+with a blind spot.
+
+| Source | Question it answers |
+| --- | --- |
+| Obsidian + Graphify | what WE already decided, and what it cost us |
+| `mcp__context7__query-docs` | what the maintainer documents — the contract |
+| `mcp__gh-grep__searchGitHub` | what N teams actually shipped — the practice |
+| WebSearch / WebFetch | everything that is not code: pricing, licensing, maintainer intent, incident history |
+
+The gap between Context7 and gh-grep — between the contract and the
+practice — is often the finding itself: an API that is documented one way
+and used another way in every real repo is telling you where the sharp
+edge is.
+
+### Querying gh-grep
+
+It runs literal grep with regex over public repos. Query with **code
+tokens**; a sentence returns noise.
+
+Evaluating a library — is this API actually used the way the README shows?
+
+```
+query: "unstable_cache(" · language: TypeScript
+→ read the call-sites: which options do people really pass, what do they
+  wrap, and what do they never do
+```
+
+Comparing two options — which one shows up in serious codebases?
+
+```
+query: "from pydantic import BaseSettings" · language: Python
+query: "from pydantic_settings import BaseSettings" · language: Python
+→ the ratio, and the migration commits between them, answer the version
+  question faster than any changelog
+```
+
+Cite what you find with the repo path, and mark it as practice, not
+contract. Where docs and practice disagree, the docs win in the
+recommendation and the divergence goes in the risks section.
+
 ## Output
 
 Research report with options, trade-offs, and recommendation

package/departments/dev/skills/stack-check/SKILL.md

@@ -27,6 +27,15 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 
 Audit current tech stack: versions, dependencies, security, performance, upgrade paths.
 
+## Evidence for the upgrade path
+
+A recommended upgrade needs more than a changelog. Search the target
+version's real configs with `mcp__gh-grep__searchGitHub` using code tokens
+from the new API — a config key, an import path, a renamed export — and read
+what teams that already migrated had to change. Repos that pin the old
+version and never moved are evidence too: treat an upgrade nobody adopted
+as a risk in its own right.
+
 ## Output
 
 Stack health report with upgrade recommendations and risk assessment

package/harness/codex/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.1.1 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -22,7 +22,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |

package/harness/copilot/copilot-instructions.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.1.1 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -22,7 +22,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |

package/harness/cursor/rules/arkaos.mdc

@@ -1,11 +1,11 @@
 ---
-description: ArkaOS v5.1.1 agent-team contract
+description: ArkaOS v5.3.0 agent-team contract
 alwaysApply: true
 ---
 
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.1.1 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -27,7 +27,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |