arkaos 4.25.0 → 4.26.0

package/README.md

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

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.25.0 — 86 agents, 17 departments, 298 skills, 270 commands, 16 ADRs.
+> v4.26.0 — 86 agents, 17 departments, 302 skills, 270 commands, 16 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.25.0
+4.26.0

package/arka/SKILL.md

@@ -47,7 +47,7 @@ complementary, not alternatives.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 86 agents. 17 departments. 298 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 302 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/bin/arka

@@ -68,7 +68,7 @@ case "${1:-}" in
     shift
     # Issue #358: the node doctor is canonical (engine/venv/hooks/security
     # + the migrated Claude-layer checks). The bash doctor only audits the
-    # legacy v1 layout — keep it strictly as the no-node fallback.
+    # legacy v1 layout — keep it strictly as the no-npx fallback.
     if command -v npx &>/dev/null; then
       npx arkaos doctor "$@"
       exit $?

package/config/claude-agents/dba.md

@@ -1,15 +1,15 @@
 ---
 name: dba
 description: >
-  Vasco — Data Platform Lead (Database & Data Engineer) (dev squad). Executes: PostgreSQL (advanced), Supabase, schema design & normalization, migration planning.
+  Vasco — Data Platform Lead — Database & Data Engineer (dev squad). Executes: PostgreSQL (advanced), Supabase, schema design & normalization, migration planning.
 model: sonnet
 ---
 
 <!-- generated by core/agents/behavioral_compiler.py from departments/dev/agents/dba.yaml — DO NOT EDIT; edit the YAML and re-run -->
 
-# Vasco — Data Platform Lead (Database & Data Engineer)
+# Vasco — Data Platform Lead — Database & Data Engineer
 
-You are Vasco, Data Platform Lead (Database & Data Engineer) of the dev squad (Tier 2). What drives you: Data systems that are fast, reliable, and correctly modeled. The failure you exist to prevent: Data loss, corruption, or slow queries bringing down production.
+You are Vasco, Data Platform Lead — Database & Data Engineer of the dev squad (Tier 2). What drives you: Data systems that are fast, reliable, and correctly modeled. The failure you exist to prevent: Data loss, corruption, or slow queries bringing down production.
 
 ## How you work
 

package/departments/dev/agents/dba.yaml

@@ -1,6 +1,6 @@
 id: dba-data-eng
 name: Vasco
-role: Data Platform Lead (Database & Data Engineer)
+role: Data Platform Lead — Database & Data Engineer
 department: dev
 tier: 2
 model: sonnet

package/departments/dev/skills/opensource-release/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: dev/opensource-release
+description: >
+  Takes an internal module or repo public WITHOUT taking its secrets
+  with it: extract the component, scrub content AND history (secrets,
+  client identifiers, internal URLs, embarrassing commits), package it
+  as a standalone citizen (license, README, CI, versioning), and verify
+  the published artifact with an adversarial re-scan before anyone
+  else can. TRIGGER: "/dev opensource-release", "open-source this",
+  "vamos abrir este módulo", "prepara isto para publicar",
+  "extrai isto para um repo público", any internal-to-public extraction.
+  SKIP: releasing a version of an already-public package ->
+  dev/release wins; secrets hygiene inside a private repo ->
+  dev/env-secrets wins; redacting a document, not a repo ->
+  kb/doc-redaction wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Open-Source Release — `/dev opensource-release`
+
+> **Agent:** Bruno (Security Engineer) | **Framework:** History-aware scrubbing, adversarial pre-publication review
+
+Publishing is the one deploy you cannot roll back. The moment a repo
+goes public, every commit it ever had goes public with it — the API key
+someone removed in 2024 but never rotated, the client name in a test
+fixture, the TODO that names an unshipped product. Mirrors and scrapers
+archive within minutes; deleting the repo afterwards deletes your copy,
+not theirs.
+
+## Phase 1 — Extract
+
+1. Decide the boundary: what goes public, and what the public part is
+   allowed to import. An internal dependency that cannot come along
+   must be replaced by an interface or the boundary is wrong.
+2. Extract into a FRESH repository with a FRESH history. Carrying the
+   internal git history into the public repo is the default disaster —
+   the scrub target becomes every blob ever committed instead of the
+   current tree. Start public history at the first public commit;
+   record the internal provenance (repo + commit hash) in a private
+   note, not in the public tree.
+
+## Phase 2 — Scrub, then prove the scrub
+
+Sweep the candidate tree for, at minimum:
+
+| Class | Examples |
+|---|---|
+| Credentials | keys, tokens, connection strings, `.env*`, CI secrets |
+| Identity leaks | client names, internal hostnames/URLs, employee data in fixtures |
+| Business leaks | pricing internals, unshipped product names, internal roadmap refs |
+| Path leaks | absolute paths exposing usernames or internal layout |
+
+Two rules make the scrub real:
+
+- **Scan the ARTIFACT, not the intention** — after packaging, run the
+  full sweep again on the exact tarball/tree that will be published
+  (the `npm pack --dry-run` + grep discipline). A scrub verified on the
+  working tree and published from a different state proves nothing.
+- **Found secrets get ROTATED, not just removed.** A credential that
+  ever sat in a candidate tree is compromised-by-assumption; removal
+  cleans the repo, rotation cleans the risk.
+
+## Phase 3 — Package as a citizen
+
+- LICENSE chosen deliberately (permissive vs copyleft is a strategy
+  decision — route it to the operator, never default silently).
+- README that stands alone: what it does, install, quickstart, no
+  internal context assumed.
+- CI on the public repo running the public tests; versioning from
+  1.0.0 or 0.x with the same discipline as any product.
+- Contribution surface decided explicitly: issues on/off, PR policy,
+  security contact.
+
+## Phase 4 — Adversarial verification
+
+Before flipping visibility, a second pass in a fresh context reviews
+the exact publishable state as a hostile outsider: what can I learn
+about the company from this tree that I should not? Only after that
+pass returns clean does the repo go public — and the first
+post-publication act is re-running the sweep against the LIVE public
+artifact.
+
+## Output
+
+```markdown
+## Open-Source Release Report
+
+**Component:** {name} · **Boundary:** {what ships / what stayed}
+**History:** fresh (internal provenance recorded privately at {ref})
+**Scrub:** {classes swept} · findings {n} · rotations {n, with owners}
+**Package:** {license} · README ✓ · CI ✓ · version {v}
+**Adversarial pass:** {clean / findings and their fixes}
+**Published:** {url} · post-publication re-scan: {clean}
+```

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

@@ -36,7 +36,7 @@ what it captures, and what survives to the next one.
 | 1 | Stale closure | callback reads state captured N renders ago | functional updater (`setX(v => ...)`) or include the dep and let the callback re-create |
 | 2 | Lying dependency array | effect reads `a`, deps say `[b]` | list what the effect READS; if that loops, the effect does too much — split it |
 | 3 | Derived state stored | `useState` mirroring a computable value, synced by effect | compute during render (`useMemo` if costly); delete the effect |
-| 4 | Key-forced remounts | `key={index}` on reorderable lists, or key changing identity every render | stable identity key; component state survives reorders |
+| 4 | Keys without identity | `key={index}` on reorderable lists (state mis-binds to the POSITION after a reorder), or key changing identity every render (full remount each time) | stable identity key; component state follows the item |
 | 5 | Effects doing render work | formatting/filtering in `useEffect` + `setState` | that is render logic — move it into render; effects are for the outside world |
 | 6 | Boundary leak (App Router) | `"use client"` at the top of a tree because one leaf needs a hook | push the directive to the leaf; a client parent drags every child into the bundle |
 | 7 | Context re-render storm | one broad context carrying fast-changing values | split contexts by change rate, memoize the provider value |

package/departments/ops/skills/harness-tune/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: ops/harness-tune
+description: >
+  Telemetry-driven tuning of the ArkaOS harness itself: reads the
+  recorded usage (MCP call telemetry, LLM cost lines, skill-budget
+  report, curated-mode leftovers) and proposes the cuts and switches
+  the data supports — MCP servers nothing called, skill surface beyond
+  the context budget, department packs installed but idle. Propose-only;
+  the operator applies. TRIGGER: "/ops harness-tune", "tune my setup",
+  "otimiza o meu harness", "o que posso cortar?", "porque está o
+  contexto tão cheio?", "que MCPs não uso?". SKIP: install health ->
+  the doctor (npx arkaos doctor) wins; cost VISIBILITY without action
+  -> /arka costs wins; business-process bottlenecks ->
+  ops/bottleneck-find wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Harness Tune — `/ops harness-tune`
+
+> **Agent:** Daniel (Operations Lead) | **Framework:** Usage-evidence pruning, propose-only changes
+
+Every MCP server registered, every skill deployed, every pack installed
+pays rent in the scarcest currency the harness has — context — whether
+it gets used or not. The bill arrives silently, every single turn. This
+skill reads the meters before proposing anything: a recommendation that
+is not backed by a telemetry line is an opinion, and opinions do not
+get to delete configuration.
+
+## Read the meters
+
+| Meter | Source | Answers |
+|---|---|---|
+| MCP usage | `~/.arkaos/telemetry/mcp-usage.jsonl` (aggregate: `core.runtime.mcp_telemetry`) | which servers were actually called, when last |
+| LLM cost | `core.runtime.llm_cost_telemetry` summaries | which sessions burn, cache hit rate |
+| Skill surface | skill-budget linter + `skills-mode.json` + manifest | deployed vs curated cut, leftovers on a curated machine |
+| Enforcement | `core.governance.enforcement_telemetry` | gates that fire often (candidates for tuning, not removal) |
+
+A meter that has no data is reported as "no data", never extrapolated —
+two days of telemetry cannot justify removing anything.
+
+## Propose (never apply)
+
+For each finding, the proposal names the evidence, the change, the
+saving, and the reversal:
+
+- MCP server with zero calls in the observation window → propose
+  removing it from the project `.mcp.json` files that carry it; note
+  the one-line restore.
+- Curated-mode machine carrying plugin-eligible leftovers → propose the
+  pack-by-pack install path instead (the doctor's skills-surface check
+  names them).
+- Full-mode machine using two departments → propose curated + the two
+  packs.
+- A gate firing constantly with high compliance → nothing to remove;
+  flag as healthy enforcement, not noise. Tuning never trades
+  governance for tokens.
+
+Hard line: user-added MCPs and project-specific servers are proposed
+for removal ONLY on zero usage, and always labeled as user-added —
+the harness does not know why the operator installed them, so the
+proposal says that too.
+
+## Output
+
+```markdown
+## Harness Tune Report — {date}
+
+**Observation window:** {days}d of telemetry ({lines} events)
+
+| # | Evidence | Proposal | Saves | Restore |
+|---|---|---|---|---|
+| 1 | {server}: 0 calls in {n}d | remove from {k} projects | {context/startup} | {one-liner} |
+
+**No-data meters:** {list, or none}
+**Healthy, untouched:** {enforcement surfaces left alone, and why}
+**Apply:** every change above is a diff the operator runs — nothing was changed by this audit.
+```

package/departments/ops/skills/session-retro/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ops/session-retro
+description: >
+  Post-session friction analysis over the actual transcript: finds the
+  corrections the operator made more than once, the tool loops, the
+  redone work, and the vague asks that cost a round-trip — and turns
+  each recurring pattern into its structural fix (a hookify predicate,
+  a recipe, a refined prompt template, a missing skill). TRIGGER:
+  "/ops session-retro", "analisa esta sessão", "what went wrong this
+  session", "porque é que isto demorou tanto?", "retro da sessão", end
+  of a long or frustrating working session. SKIP: capturing an
+  APPROVED feature build for reuse -> arka-recipes wins; you already
+  know the predicate to enforce -> ops/hookify wins; team/human
+  retrospectives -> lead/team-health wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Session Retro — `/ops session-retro`
+
+> **Agent:** Daniel (Operations Lead) | **Framework:** Transcript friction mining, pattern-to-fix routing
+
+You shipped. The tests are green, the PR is merged, and nobody asks
+what the session cost to get there — the correction typed three times,
+the file re-read five, the plan that bounced twice for the same reason.
+That cost repeats next session, and the one after, until someone reads
+the transcript looking for it. The deliverable was reviewed; the
+PROCESS never is. This is that review.
+
+## Mine the transcript
+
+Sources, in order of reliability: the session transcript itself, the
+telemetry the hooks recorded during it (`~/.arkaos/telemetry/` —
+stop-lint events, tool-loop detections, compliance lines), and the git
+reflog of the period. Findings must quote their instances — a friction
+claim without at least two concrete occurrences is an anecdote and is
+reported as such or dropped.
+
+| Pattern | Signature in the transcript |
+|---|---|
+| Repeated correction | operator states the same guidance ≥2 times, any phrasing |
+| Tool loop | same call, same target, no state change between (the tool-loop detector's events, plus manual scan) |
+| Redone work | an artifact written, then rewritten from scratch after a bounce that named a knowable-in-advance defect |
+| Vague-ask round-trip | request → clarification exchange → the ACTUAL request (the refine pattern, observed after the fact) |
+| Context churn | the same file read repeatedly far apart — a sign the fact belonged in memory or a doc |
+
+## Route each pattern to its structural fix
+
+The retro's output is not a list of regrets — every confirmed pattern
+maps to exactly one fix owner:
+
+- Repeated correction with a decidable predicate → **ops/hookify**
+  (hand it the instances; they are the evidence Step 1 needs).
+- Correction that needs judgment → memory entry or department skill
+  gap, named explicitly.
+- Redone work after a preventable bounce → the checklist/skill that
+  would have caught it BEFORE the first attempt.
+- Vague-ask round-trips → the prompt template or refine flow that
+  front-loads the missing parameters.
+- Context churn → the doc, memory, or CLAUDE.md line where the fact
+  should permanently live.
+
+A pattern with no viable fix is stated as accepted cost — visible,
+priced, and chosen, rather than silently paid again.
+
+## Output
+
+```markdown
+## Session Retro — {session/date}
+
+**Shipped:** {what the session delivered} · **Friction cost:** {rough
+turns/time attributable to the patterns below}
+
+| # | Pattern | Instances | Fix | Owner |
+|---|---|---|---|---|
+| 1 | {repeated correction: "stage by explicit path"} | {turn refs} | hookify predicate | ops/hookify |
+
+**Accepted costs:** {none, or the priced list}
+**One change for next session:** {the single highest-leverage fix}
+```

package/departments/ops/skills/workspace-audit/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ops/workspace-audit
+description: >
+  Sweeps every repository in the workspace for the entropy that
+  accumulates between projects: dirty working trees, unpushed commits,
+  orphaned branches, forgotten stashes, repos without remotes, and
+  secrets sitting outside .gitignore — then reports per repo with the
+  one command that clears each finding. TRIGGER: "/ops workspace-audit",
+  "audit my workspace", "varre os meus projetos", "que repos estão
+  sujos?", "o que tenho por commitar?", periodic hygiene, and after any
+  tool that mass-edits files across projects. SKIP: branch/merge
+  discipline within one change -> ops/github-ops wins; ArkaOS install
+  health -> the doctor (npx arkaos doctor) wins; one project's
+  dependency risk -> dev/dependency-audit wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Workspace Audit — `/ops workspace-audit`
+
+> **Agent:** Daniel (Operations Lead) | **Framework:** Read-only sweep, finding-to-command mapping
+
+Workspaces do not break; they silt. One repo keeps a dirty tree from a
+config sync, another holds a commit that never got pushed, a third has
+a stash nobody remembers making — each harmless alone, none announced,
+all invisible until the day one of them eats an afternoon or, worse, a
+piece of work. The sweep exists because no single project's tooling
+looks ACROSS projects.
+
+## Sweep
+
+For every git repository under the workspace roots (honoring the
+operator's project layout — e.g. `~/Herd` for Laravel, `~/Work` for
+Node/Nuxt/Python — plus any explicitly given path):
+
+| # | Check | Finding when |
+|---|---|---|
+| 1 | Working tree | `git status --porcelain` non-empty |
+| 2 | Unpushed work | commits ahead of upstream, or branch with no upstream |
+| 3 | Stashes | `git stash list` non-empty (each stash is work in limbo) |
+| 4 | Orphaned branches | local branches fully merged into the default branch, or with no activity beyond an age threshold |
+| 5 | No remote | repository with zero remotes (single-disk work) |
+| 6 | Secrets exposure | `.env*` / key files present AND not matched by .gitignore |
+| 7 | Detached HEAD | repo parked on no branch |
+
+**The audit is strictly read-only.** It runs inspection commands only
+and never fixes anything itself — a sweep that mutates sixty repos to
+"help" is a bigger incident than anything it would find. Every finding
+ships with the exact command that clears it; running them is the
+operator's call, repo by repo.
+
+## Triage
+
+Findings are ranked by loss potential, not by count:
+
+1. **Work at risk** — dirty trees, unpushed commits, stashes, detached
+   HEADs, no-remote repos: things that can LOSE work.
+2. **Exposure** — secrets outside .gitignore: things that can LEAK.
+3. **Clutter** — orphaned branches: things that cost attention only.
+
+A workspace with 40 clutter findings and one unpushed repo leads with
+the unpushed repo.
+
+## Output
+
+```markdown
+## Workspace Audit — {date}
+
+**Roots:** {paths} · **Repos scanned:** {n} · **Clean:** {n}
+
+### Work at risk ({n})
+| Repo | Finding | Clear with |
+|---|---|---|
+| {path} | {e.g. 3 commits unpushed on feat/x} | `git push origin feat/x` |
+
+### Exposure ({n})
+| Repo | Finding | Clear with |
+
+### Clutter ({n})
+{collapsed list: repo — branches}
+
+**Verdict:** {the one thing to do first, and why it outranks the rest}
+```
+
+Repeated audits should trend toward boring: a finding that reappears
+every sweep is a process gap — route it to ops/hookify or an SOP
+instead of clearing it by hand a fourth time.

package/harness/codex/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.25.0 — 86 agents, 17 departments, 298 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.26.0 — 86 agents, 17 departments, 302 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.
@@ -46,7 +46,7 @@ Adopt the matching persona when executing department work:
 - **brand**: Iris (Design Ops Lead) · Valentina (Creative Director) · Isabel (Visual Designer) · Júlia (UX Strategist) · Leo (Component Library Standardizer) · Mateus (Brand Strategist) · Nia (Design Extraction Engineer) · Oren (Accessibility Auditor) · Renata (UX Researcher) · Sofia D. (UX/UI Designer)
 - **community**: Beatriz (Community Strategist) · Maria (Community Manager) · Tania (Engagement & Gamification Designer)
 - **content**: Rafael (Content Strategist) · Simão (Video Producer & Production Lead) · Dinis (Information Compiler) · Filipe (Viral Content Engineer) · Joana (Scriptwriter) · Madalena (Content Researcher) · Margarida (Trends & Niche Analyst) · Nuno (Repurpose & Distribution Specialist)
-- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead (Database & Data Engineer)) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
+- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead — Database & Data Engineer) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
 - **ecom**: Ricardo (E-Commerce Director) · Alice (CRO Specialist) · Catarina (Lifecycle & Retention Manager) · David (Commerce Engineer)
 - **fin**: Helena (Chief Financial Officer) · Leonor (Financial Analyst) · Rui (Investment & Fundraising Strategist)
 - **kb**: Clara (Knowledge Director) · Francisco (Research Analyst) · Helena C. (Knowledge Curator) · Tomas Jr (Data Collector)
@@ -61,7 +61,7 @@ Adopt the matching persona when executing department work:
 - **sales**: Miguel (Sales Director) · Ines S. (Sales Operations Analyst) · Joao (Sales Closer) · Martim (SDR / Pre-Sales)
 - **strat**: Tomas (Chief Strategist) · Guilherme (Decision Quality & Strategic Foresight) · Lucas (Market & Competitive Intelligence Analyst) · Marta S. (Business Model Designer)
 
-## Stack conventions
+## Stack Conventions
 
 Apply the section matching the files you touch.
 

package/harness/copilot/copilot-instructions.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.25.0 — 86 agents, 17 departments, 298 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.26.0 — 86 agents, 17 departments, 302 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.
@@ -46,7 +46,7 @@ Adopt the matching persona when executing department work:
 - **brand**: Iris (Design Ops Lead) · Valentina (Creative Director) · Isabel (Visual Designer) · Júlia (UX Strategist) · Leo (Component Library Standardizer) · Mateus (Brand Strategist) · Nia (Design Extraction Engineer) · Oren (Accessibility Auditor) · Renata (UX Researcher) · Sofia D. (UX/UI Designer)
 - **community**: Beatriz (Community Strategist) · Maria (Community Manager) · Tania (Engagement & Gamification Designer)
 - **content**: Rafael (Content Strategist) · Simão (Video Producer & Production Lead) · Dinis (Information Compiler) · Filipe (Viral Content Engineer) · Joana (Scriptwriter) · Madalena (Content Researcher) · Margarida (Trends & Niche Analyst) · Nuno (Repurpose & Distribution Specialist)
-- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead (Database & Data Engineer)) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
+- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead — Database & Data Engineer) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
 - **ecom**: Ricardo (E-Commerce Director) · Alice (CRO Specialist) · Catarina (Lifecycle & Retention Manager) · David (Commerce Engineer)
 - **fin**: Helena (Chief Financial Officer) · Leonor (Financial Analyst) · Rui (Investment & Fundraising Strategist)
 - **kb**: Clara (Knowledge Director) · Francisco (Research Analyst) · Helena C. (Knowledge Curator) · Tomas Jr (Data Collector)
@@ -61,7 +61,7 @@ Adopt the matching persona when executing department work:
 - **sales**: Miguel (Sales Director) · Ines S. (Sales Operations Analyst) · Joao (Sales Closer) · Martim (SDR / Pre-Sales)
 - **strat**: Tomas (Chief Strategist) · Guilherme (Decision Quality & Strategic Foresight) · Lucas (Market & Competitive Intelligence Analyst) · Marta S. (Business Model Designer)
 
-## Stack conventions
+## Stack Conventions
 
 Apply the section matching the files you touch.
 

package/harness/cursor/rules/arkaos-stack-laravel.mdc

@@ -1,5 +1,5 @@
 ---
-description: ArkaOS laravel stack conventions
+description: ArkaOS Laravel stack conventions
 globs: app/**/*.php, routes/**/*.php, database/**/*.php, config/**/*.php, tests/**/*.php
 alwaysApply: false
 ---

package/harness/cursor/rules/arkaos-stack-node.mdc

@@ -1,5 +1,5 @@
 ---
-description: ArkaOS node stack conventions
+description: ArkaOS Node stack conventions
 globs: **/*.js, **/*.mjs, **/*.cjs, **/*.ts
 alwaysApply: false
 ---

package/harness/cursor/rules/arkaos-stack-nuxt.mdc

@@ -1,5 +1,5 @@
 ---
-description: ArkaOS nuxt stack conventions
+description: ArkaOS Nuxt stack conventions
 globs: **/*.vue, composables/**, pages/**, layouts/**, server/**, nuxt.config.*
 alwaysApply: false
 ---

package/harness/cursor/rules/arkaos-stack-php.mdc

@@ -1,5 +1,5 @@
 ---
-description: ArkaOS php stack conventions
+description: ArkaOS PHP stack conventions
 globs: **/*.php
 alwaysApply: false
 ---

package/harness/cursor/rules/arkaos-stack-python.mdc

@@ -1,5 +1,5 @@
 ---
-description: ArkaOS python stack conventions
+description: ArkaOS Python stack conventions
 globs: **/*.py
 alwaysApply: false
 ---

package/harness/cursor/rules/arkaos-stack-react.mdc

@@ -1,5 +1,5 @@
 ---
-description: ArkaOS react stack conventions
+description: ArkaOS React stack conventions
 globs: **/*.tsx, **/*.jsx
 alwaysApply: false
 ---

package/harness/cursor/rules/arkaos-stack-vue.mdc

@@ -1,5 +1,5 @@
 ---
-description: ArkaOS vue stack conventions
+description: ArkaOS Vue stack conventions
 globs: **/*.vue
 alwaysApply: false
 ---

package/harness/cursor/rules/arkaos.mdc

@@ -1,11 +1,11 @@
 ---
-description: ArkaOS v4.25.0 agent-team contract
+description: ArkaOS v4.26.0 agent-team contract
 alwaysApply: true
 ---
 
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.25.0 — 86 agents, 17 departments, 298 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.26.0 — 86 agents, 17 departments, 302 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.
@@ -51,7 +51,7 @@ Adopt the matching persona when executing department work:
 - **brand**: Iris (Design Ops Lead) · Valentina (Creative Director) · Isabel (Visual Designer) · Júlia (UX Strategist) · Leo (Component Library Standardizer) · Mateus (Brand Strategist) · Nia (Design Extraction Engineer) · Oren (Accessibility Auditor) · Renata (UX Researcher) · Sofia D. (UX/UI Designer)
 - **community**: Beatriz (Community Strategist) · Maria (Community Manager) · Tania (Engagement & Gamification Designer)
 - **content**: Rafael (Content Strategist) · Simão (Video Producer & Production Lead) · Dinis (Information Compiler) · Filipe (Viral Content Engineer) · Joana (Scriptwriter) · Madalena (Content Researcher) · Margarida (Trends & Niche Analyst) · Nuno (Repurpose & Distribution Specialist)
-- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead (Database & Data Engineer)) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
+- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead — Database & Data Engineer) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
 - **ecom**: Ricardo (E-Commerce Director) · Alice (CRO Specialist) · Catarina (Lifecycle & Retention Manager) · David (Commerce Engineer)
 - **fin**: Helena (Chief Financial Officer) · Leonor (Financial Analyst) · Rui (Investment & Fundraising Strategist)
 - **kb**: Clara (Knowledge Director) · Francisco (Research Analyst) · Helena C. (Knowledge Curator) · Tomas Jr (Data Collector)
@@ -66,7 +66,7 @@ Adopt the matching persona when executing department work:
 - **sales**: Miguel (Sales Director) · Ines S. (Sales Operations Analyst) · Joao (Sales Closer) · Martim (SDR / Pre-Sales)
 - **strat**: Tomas (Chief Strategist) · Guilherme (Decision Quality & Strategic Foresight) · Lucas (Market & Competitive Intelligence Analyst) · Marta S. (Business Model Designer)
 
-## Stack conventions
+## Stack Conventions
 
 Path-scoped rules in this directory (`arkaos-stack-*.mdc`) apply automatically to matching files.
 

package/harness/gemini/GEMINI.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.25.0 — 86 agents, 17 departments, 298 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.26.0 — 86 agents, 17 departments, 302 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.
@@ -46,7 +46,7 @@ Adopt the matching persona when executing department work:
 - **brand**: Iris (Design Ops Lead) · Valentina (Creative Director) · Isabel (Visual Designer) · Júlia (UX Strategist) · Leo (Component Library Standardizer) · Mateus (Brand Strategist) · Nia (Design Extraction Engineer) · Oren (Accessibility Auditor) · Renata (UX Researcher) · Sofia D. (UX/UI Designer)
 - **community**: Beatriz (Community Strategist) · Maria (Community Manager) · Tania (Engagement & Gamification Designer)
 - **content**: Rafael (Content Strategist) · Simão (Video Producer & Production Lead) · Dinis (Information Compiler) · Filipe (Viral Content Engineer) · Joana (Scriptwriter) · Madalena (Content Researcher) · Margarida (Trends & Niche Analyst) · Nuno (Repurpose & Distribution Specialist)
-- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead (Database & Data Engineer)) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
+- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead — Database & Data Engineer) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
 - **ecom**: Ricardo (E-Commerce Director) · Alice (CRO Specialist) · Catarina (Lifecycle & Retention Manager) · David (Commerce Engineer)
 - **fin**: Helena (Chief Financial Officer) · Leonor (Financial Analyst) · Rui (Investment & Fundraising Strategist)
 - **kb**: Clara (Knowledge Director) · Francisco (Research Analyst) · Helena C. (Knowledge Curator) · Tomas Jr (Data Collector)
@@ -61,7 +61,7 @@ Adopt the matching persona when executing department work:
 - **sales**: Miguel (Sales Director) · Ines S. (Sales Operations Analyst) · Joao (Sales Closer) · Martim (SDR / Pre-Sales)
 - **strat**: Tomas (Chief Strategist) · Guilherme (Decision Quality & Strategic Foresight) · Lucas (Market & Competitive Intelligence Analyst) · Marta S. (Business Model Designer)
 
-## Stack conventions
+## Stack Conventions
 
 Apply the section matching the files you touch.
 

package/harness/opencode/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.25.0 — 86 agents, 17 departments, 298 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.26.0 — 86 agents, 17 departments, 302 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.
@@ -46,7 +46,7 @@ Adopt the matching persona when executing department work:
 - **brand**: Iris (Design Ops Lead) · Valentina (Creative Director) · Isabel (Visual Designer) · Júlia (UX Strategist) · Leo (Component Library Standardizer) · Mateus (Brand Strategist) · Nia (Design Extraction Engineer) · Oren (Accessibility Auditor) · Renata (UX Researcher) · Sofia D. (UX/UI Designer)
 - **community**: Beatriz (Community Strategist) · Maria (Community Manager) · Tania (Engagement & Gamification Designer)
 - **content**: Rafael (Content Strategist) · Simão (Video Producer & Production Lead) · Dinis (Information Compiler) · Filipe (Viral Content Engineer) · Joana (Scriptwriter) · Madalena (Content Researcher) · Margarida (Trends & Niche Analyst) · Nuno (Repurpose & Distribution Specialist)
-- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead (Database & Data Engineer)) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
+- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead — Database & Data Engineer) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
 - **ecom**: Ricardo (E-Commerce Director) · Alice (CRO Specialist) · Catarina (Lifecycle & Retention Manager) · David (Commerce Engineer)
 - **fin**: Helena (Chief Financial Officer) · Leonor (Financial Analyst) · Rui (Investment & Fundraising Strategist)
 - **kb**: Clara (Knowledge Director) · Francisco (Research Analyst) · Helena C. (Knowledge Curator) · Tomas Jr (Data Collector)
@@ -61,7 +61,7 @@ Adopt the matching persona when executing department work:
 - **sales**: Miguel (Sales Director) · Ines S. (Sales Operations Analyst) · Joao (Sales Closer) · Martim (SDR / Pre-Sales)
 - **strat**: Tomas (Chief Strategist) · Guilherme (Decision Quality & Strategic Foresight) · Lucas (Market & Competitive Intelligence Analyst) · Marta S. (Business Model Designer)
 
-## Stack conventions
+## Stack Conventions
 
 Apply the section matching the files you touch.
 

package/harness/zed/.rules

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v4.25.0 — 86 agents, 17 departments, 298 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v4.26.0 — 86 agents, 17 departments, 302 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.
@@ -46,7 +46,7 @@ Adopt the matching persona when executing department work:
 - **brand**: Iris (Design Ops Lead) · Valentina (Creative Director) · Isabel (Visual Designer) · Júlia (UX Strategist) · Leo (Component Library Standardizer) · Mateus (Brand Strategist) · Nia (Design Extraction Engineer) · Oren (Accessibility Auditor) · Renata (UX Researcher) · Sofia D. (UX/UI Designer)
 - **community**: Beatriz (Community Strategist) · Maria (Community Manager) · Tania (Engagement & Gamification Designer)
 - **content**: Rafael (Content Strategist) · Simão (Video Producer & Production Lead) · Dinis (Information Compiler) · Filipe (Viral Content Engineer) · Joana (Scriptwriter) · Madalena (Content Researcher) · Margarida (Trends & Niche Analyst) · Nuno (Repurpose & Distribution Specialist)
-- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead (Database & Data Engineer)) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
+- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead — Database & Data Engineer) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
 - **ecom**: Ricardo (E-Commerce Director) · Alice (CRO Specialist) · Catarina (Lifecycle & Retention Manager) · David (Commerce Engineer)
 - **fin**: Helena (Chief Financial Officer) · Leonor (Financial Analyst) · Rui (Investment & Fundraising Strategist)
 - **kb**: Clara (Knowledge Director) · Francisco (Research Analyst) · Helena C. (Knowledge Curator) · Tomas Jr (Data Collector)
@@ -61,7 +61,7 @@ Adopt the matching persona when executing department work:
 - **sales**: Miguel (Sales Director) · Ines S. (Sales Operations Analyst) · Joao (Sales Closer) · Martim (SDR / Pre-Sales)
 - **strat**: Tomas (Chief Strategist) · Guilherme (Decision Quality & Strategic Foresight) · Lucas (Market & Competitive Intelligence Analyst) · Marta S. (Business Model Designer)
 
-## Stack conventions
+## Stack Conventions
 
 Apply the section matching the files you touch.
 

package/installer/doctor.js

@@ -87,9 +87,10 @@ export function statuslineConfigured(
   }
 }
 
-// gotchas.json is live v2 state: capture/collector.py appends to it and
-// `/arka evolve` (#348) ingests it. Missing means capture never ran;
-// corrupt means evolve will choke.
+// gotchas.json is live v2 state: the PostToolUse hook writes it
+// (core/hooks/post_tool_use.py::_store_gotcha) and `/arka evolve`
+// (#348) ingests it. Missing means capture never ran; corrupt means
+// evolve will choke.
 export function gotchasHealthy(
   gotchasPath = join(INSTALL_DIR, "gotchas.json")
 ) {

package/installer/harness-bundle.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // Multi-runtime instruction bundles, generated by scripts/harness_gen.py
@@ -16,8 +16,13 @@ export function bundleDir(target) {
 // Content of one bundle file, or null when the bundle is absent (a
 // source tree without a generated harness/ — callers must fall back
 // loudly, never write a pointer to a file that does not exist).
+// Containment guard: a rel that escapes the target's bundle directory
+// resolves to null — defense-in-depth, unreachable from today's
+// hardcoded callers.
 export function readBundleFile(target, rel) {
-  const path = join(bundleDir(target), rel);
+  const base = resolve(bundleDir(target));
+  const path = resolve(base, rel);
+  if (path !== base && !path.startsWith(base + sep)) return null;
   return existsSync(path) ? readFileSync(path, "utf-8") : null;
 }
 

package/knowledge/agents-registry-v2.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "version": "2.0.0",
-    "generated": "2026-07-20T21:08:57.022558",
+    "generated": "2026-07-21T11:11:29.016401",
     "total_agents": 86,
     "generator": "core/agents/registry_gen.py",
     "tiers": {
@@ -1586,7 +1586,7 @@
     {
       "id": "dba-data-eng",
       "name": "Vasco",
-      "role": "Data Platform Lead (Database & Data Engineer)",
+      "role": "Data Platform Lead — Database & Data Engineer",
       "department": "dev",
       "tier": 2,
       "model": "sonnet",

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "4.25.0",
+    "version": "4.26.0",
     "marketplace": "arkaos"
   },
   "structural": {
@@ -1373,6 +1373,19 @@
         "origin": "arkaos"
       }
     },
+    "harness-tune": {
+      "depts": [
+        "ops"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-ops@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "headline-write": {
       "depts": [
         "landing"
@@ -2054,6 +2067,19 @@
         "origin": "arkaos"
       }
     },
+    "opensource-release": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "operations": {
       "depts": [
         "ops"
@@ -2742,6 +2768,19 @@
         "origin": "arkaos"
       }
     },
+    "session-retro": {
+      "depts": [
+        "ops"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-ops@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "shape-pitch": {
       "depts": [
         "pm"
@@ -3300,6 +3339,19 @@
         "origin": "arkaos"
       }
     },
+    "workspace-audit": {
+      "depts": [
+        "ops"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-ops@arkaos"
+      ],
+      "collision": false,
+      "provenance": {
+        "origin": "arkaos"
+      }
+    },
     "write-as-persona": {
       "depts": [
         "kb"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.25.0",
+  "version": "4.26.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.25.0"
+version = "4.26.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/harness_gen.py

@@ -71,6 +71,13 @@ DIR_TO_PREFIX = {
 # target's context stop being read — the budget is the feature.
 MAIN_FILE_BUDGET_BYTES = 16_000
 
+# Stack slug -> display name for user-facing frontmatter (title() would
+# render "Php").
+STACK_DISPLAY = {
+    "laravel": "Laravel", "node": "Node", "nuxt": "Nuxt", "php": "PHP",
+    "python": "Python", "react": "React", "vue": "Vue",
+}
+
 
 def _load_agents() -> list[dict]:
     data = json.loads(
@@ -182,7 +189,7 @@ Adopt the matching persona when executing department work:
 
 {_agent_index(agents)}
 
-## Stack conventions
+## Stack Conventions
 
 Apply the section matching the files you touch.
 
@@ -204,9 +211,9 @@ def _cursor_files() -> dict[str, str]:
     body = _contract_body()
     # Strip the stack section from the always-on rule — stacks ship as
     # individually scoped .mdc files below, Cursor's native strength.
-    main = body.split("## Stack conventions")[0].rstrip()
+    main = body.split("## Stack Conventions")[0].rstrip()
     main += (
-        "\n\n## Stack conventions\n\nPath-scoped rules in this directory "
+        "\n\n## Stack Conventions\n\nPath-scoped rules in this directory "
         "(`arkaos-stack-*.mdc`) apply automatically to matching files.\n"
     )
     files["rules/arkaos.mdc"] = (
@@ -215,8 +222,9 @@ def _cursor_files() -> dict[str, str]:
     )
     for stack, globs, rule_body in _stack_rules():
         globs_line = ", ".join(globs)
+        display = STACK_DISPLAY.get(stack, stack.title())
         files[f"rules/arkaos-stack-{stack}.mdc"] = (
-            f"---\ndescription: ArkaOS {stack} stack conventions\n"
+            f"---\ndescription: ArkaOS {display} stack conventions\n"
             f"globs: {globs_line}\nalwaysApply: false\n---\n\n"
             f"{rule_body}\n"
         )
@@ -247,22 +255,27 @@ def check_budget(files: dict[str, str]) -> list[str]:
     return over
 
 
-def main() -> int:
-    files = generate()
-    over = check_budget(files)
-    if over:
-        print("BUDGET EXCEEDED:\n  " + "\n  ".join(over))
-        return 1
-    if HARNESS_DIR.exists():
-        for stale in HARNESS_DIR.rglob("*"):
+def write_bundle(files: dict[str, str], harness_dir: Path) -> None:
+    """Write the bundle, removing files a previous run left behind."""
+    if harness_dir.exists():
+        for stale in harness_dir.rglob("*"):
             if stale.is_file():
-                rel = str(stale.relative_to(HARNESS_DIR))
+                rel = str(stale.relative_to(harness_dir))
                 if rel not in files:
                     stale.unlink()
     for rel, content in files.items():
-        target = HARNESS_DIR / rel
+        target = harness_dir / rel
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_text(content)
+
+
+def main() -> int:
+    files = generate()
+    over = check_budget(files)
+    if over:
+        print("BUDGET EXCEEDED:\n  " + "\n  ".join(over))
+        return 1
+    write_bundle(files, HARNESS_DIR)
     total = sum(len(c.encode()) for c in files.values())
     print(
         f"harness generated: {len(files)} files, 6 targets, "