arkaos 4.24.0 → 4.26.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-86 agents. 17 departments. 294 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.24.0 — 86 agents, 17 departments, 294 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.24.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. 294 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

@@ -66,6 +66,14 @@ case "${1:-}" in
     ;;
   doctor)
     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-npx fallback.
+    if command -v npx &>/dev/null; then
+      npx arkaos doctor "$@"
+      exit $?
+    fi
+    echo "npx not found — falling back to the legacy v1 doctor (limited scope)." >&2
     bash "$HOME/.local/bin/arka-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/config/claude-agents/shadcn-padronizer.md

@@ -1,15 +1,15 @@
 ---
 name: shadcn-padronizer
 description: >
-  Leo — Component Library Padronizer (brand squad). Executes: shadcn/ui component generation and customisation, Radix UI primitives integration, Tailwind configuration and theme tokens, CVA variants and slot patterns.
+  Leo — Component Library Standardizer (brand squad). Executes: shadcn/ui component generation and customisation, Radix UI primitives integration, Tailwind configuration and theme tokens, CVA variants and slot patterns.
 model: sonnet
 ---
 
 <!-- generated by core/agents/behavioral_compiler.py from departments/brand/agents/design-ops/shadcn-padronizer.yaml — DO NOT EDIT; edit the YAML and re-run -->
 
-# Leo — Component Library Padronizer
+# Leo — Component Library Standardizer
 
-You are Leo, Component Library Padronizer of the brand squad (Tier 2). What drives you: One canonical component, used everywhere, evolving cleanly. The failure you exist to prevent: Five teams shipping five Button components that diverge over a quarter.
+You are Leo, Component Library Standardizer of the brand squad (Tier 2). What drives you: One canonical component, used everywhere, evolving cleanly. The failure you exist to prevent: Five teams shipping five Button components that diverge over a quarter.
 
 ## How you work
 

package/departments/brand/agents/design-ops/shadcn-padronizer.yaml

@@ -1,6 +1,6 @@
 id: shadcn-padronizer-leo
 name: Leo
-role: Component Library Padronizer
+role: Component Library Standardizer
 department: brand
 tier: 2
 model: sonnet

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/build-fix/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: dev/build-fix
+description: >
+  Systematic build-failure diagnosis: read the FIRST error bottom-up,
+  reproduce it in isolation, classify it (dependency, config, code,
+  toolchain, cache), fix the root cause, and prove the fix with two
+  clean builds — with per-ecosystem playbooks for the failure
+  signatures of Laravel/PHP, Node/TS, Vue/Nuxt, React/Next, and Python.
+  TRIGGER: "/dev build-fix", "the build is broken", "o build está a
+  falhar", "compila localmente mas falha no CI", "npm run build
+  rebenta", "composer install falha", "arranja o build"; any red build
+  whose error output exists. SKIP: the code builds but tests fail ->
+  dev/code-review or dev/app-test wins; designing the pipeline itself
+  -> dev/ci-cd-pipeline wins; a production outage -> dev/incident wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Build Fix — `/dev build-fix`
+
+> **Agent:** Paulo (Tech Lead) | **Framework:** Root-cause classification, first-error discipline
+
+A failing build is the most honest bug report you will ever receive:
+deterministic, reproducible, and pointing at itself. Almost every hour
+lost to a broken build is lost the same way — fixing the LAST error on
+the screen, which is usually a cascade symptom of the first one, or
+reaching for the folk remedy (delete the lockfile, clear every cache,
+reinstall the world) before reading what the tool actually said.
+
+## Method
+
+1. **Find the first error.** Scroll past the cascade; the root error is
+   the earliest one, and everything after it is noise until proven
+   otherwise.
+2. **Reproduce in isolation.** Run the failing step alone, from a clean
+   shell, with the project's pinned tool versions. A build that only
+   fails inside CI is still reproducible — replicate the CI's inputs
+   (env vars, lockfile, node/php/python version) locally before
+   touching anything.
+3. **Classify** the root error into exactly one bucket:
+   | Bucket | Signature |
+   |---|---|
+   | Dependency | resolver conflicts, missing package, lockfile drift |
+   | Config | tool config rejects input, wrong paths, env var absent |
+   | 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
+   the compiler was right about is a deferred production bug.
+5. **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.
+
+## Ecosystem playbooks
+
+### Laravel / PHP
+
+- `Class not found` after moving a file → regenerate the autoload map
+  (`composer dump-autoload`); if it persists, the namespace does not
+  match the path — fix the namespace, not the autoloader.
+- `composer install` resolver conflict → read WHICH two constraints
+  collide before touching version pins; widening the wrong one
+  downgrades half the tree.
+- Migration failure mid-build → the schema state is now ahead of the
+  migration table; inspect before re-running, never loop `migrate:fresh`
+  on shared databases.
+
+### Node / TypeScript
+
+- `tsc` errors that runtime never hits → the types drifted from the
+  code; fix the types, do not add `as any` (the compiler is the only
+  reviewer that reads every call site).
+- Works locally, fails in CI → lockfile drift: CI runs `npm ci` (exact
+  lockfile) while local `npm install` mutated it. Commit the lockfile
+  the build actually needs.
+- `ERR_REQUIRE_ESM` / `Cannot use import` → an ESM-only dependency in a
+  CJS context; align the importing module's format instead of pinning
+  the dependency to a dead major.
+
+### Vue / Nuxt
+
+- Auto-import resolution failures (`X is not defined` only in build) →
+  the dev server tolerates what nitro's build does not; add the
+  explicit import.
+- Hydration-safe code that fails at BUILD time in SSR → browser-only
+  API executed at module top level; move it inside a lifecycle hook or
+  guard it.
+
+### React / Next.js
+
+- Server/client boundary violations (`useState in a Server Component`)
+  → mark the leaf `"use client"`, never the whole tree — pushing the
+  directive up quietly moves the entire subtree to the client bundle.
+- Build-time data fetching failures → a page assumed a runtime env var
+  at static-generation time; decide dynamic vs static explicitly.
+
+### Python
+
+- Import works in the repl, fails in the build → the venv the build
+  uses is not the venv you activated; print `sys.executable` in the
+  failing context before debugging imports.
+- Resolver backtracking forever → over-constrained pins; loosen the
+  pins you own, never the transitive ones.
+- Circular import only at build/collect time → the cycle was always
+  there; imports inside functions defer it, moving the shared symbol
+  out removes it.
+
+## Output
+
+```markdown
+## Build Fix Report
+
+**Failing step:** {command} · **First error:** {file}:{line} — {message}
+**Bucket:** {dependency|config|code|toolchain|cache}
+**Root cause:** {one sentence}
+**Fix:** {what changed and why it addresses the root}
+**Proof:** incremental build exit 0 · clean build exit 0 (commands on record)
+```
+
+A build fixed without the two-build proof, or a symptom silenced with a
+cast or a cache clear, does not close this skill.

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

@@ -0,0 +1,86 @@
+---
+name: dev/react-review
+description: >
+  React / Next.js review for the framework's own traps — stale closures
+  in hooks, dependency arrays that lie, derived state stored instead of
+  computed, keys that force remounts, effects doing render work, and
+  server/client boundary leaks in the App Router — with the fix each
+  needs. Hooks and TypeScript assumed. TRIGGER: "/dev react-review",
+  "review this React", "review the Next.js", "revê este componente
+  React", "revê o hook", "porque é que o efeito corre duas vezes?", any
+  diff touching *.tsx components or custom hooks. SKIP:
+  language-agnostic review -> dev/code-review wins; TypeScript type
+  design without React specifics -> dev/typescript-review wins; a
+  handler-ordering/state-cancellation bug -> dev/click-path-audit wins;
+  visual/brand review -> brand/design-review wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# React Review — `/dev react-review`
+
+> **Agent:** Diana (Senior Frontend Developer) | **Framework:** Hooks semantics, render-cycle discipline, RSC boundaries
+
+Where Vue's traps announce themselves — reactivity silently lost is
+still lost — React's traps ship working code that is wrong later: the
+closure that captured last render's state, the dependency array that
+omits what the effect reads, the memo that never invalidates. This
+review walks the render cycle, not the file: what each render reads,
+what it captures, and what survives to the next one.
+
+## The traps, and the fix each needs
+
+| # | Trap | Signature | Fix |
+|---|------|-----------|-----|
+| 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 | 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 |
+| 8 | Unstable references as props | inline objects/functions into memoized children | hoist or `useCallback`/`useMemo` — or drop the memo, half-memoized is unmemoized |
+
+## Process
+
+For every component and custom hook in scope:
+
+1. **Trace one render**: what it reads, what it computes, what it
+   captures in closures handed to children, effects, or timers.
+2. **Interrogate every `useEffect`**: does it synchronize with an
+   external system (fetch, subscription, DOM)? If it only moves state
+   around, it is a trap-3 or trap-5 candidate.
+3. **Check every dependency array against the closure it feeds** — the
+   array documents what the closure reads; any omission is a latent
+   staleness bug, not an optimization.
+4. **Walk the server/client boundary** (Next.js App Router): where does
+   `"use client"` sit, and does anything serialize a non-serializable
+   prop across it?
+5. **Confirm list keys carry identity**, not position.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- an async callback using state without a functional updater → the
+  stale-closure race it hides
+- `useEffect` + `setState` whose only input is other state → the
+  derived-state rewrite that deletes both
+- a `"use client"` higher than the hook that needs it → the bundle cost
+  and the RSC benefits silently forfeited
+
+## Output
+
+```markdown
+## React Review Report
+
+**Scope:** {components / hooks reviewed}
+
+### {Component / hook} — {file}:{line}
+**Trap:** {#N name} · **Evidence:** {what the render trace shows}
+**Consequence:** {what goes wrong, when}
+**Fix:** {the specific rewrite}
+
+**Verdict:** {clean / N findings, ranked by user impact}
+```

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/hookify/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ops/hookify
+description: >
+  Compiles a repeated correction into a deterministic hook: identify
+  the behavior that keeps being corrected by hand, express it as a
+  machine-checkable predicate, and install it on the right ArkaOS hook
+  surface (PreToolUse deny, Stop lint, UserPromptSubmit nudge) —
+  warn-first with telemetry, hard only when the false-positive rate
+  earns it. TRIGGER: "/ops hookify", "make this automatic", "torna isto
+  automático", "estou farto de corrigir isto", "enforce this rule",
+  "isto devia ser um hook"; the third manual correction of the same
+  behavior. SKIP: capturing a reusable feature build -> arka-recipes
+  wins; automating a business process -> ops/workflow-automate wins;
+  writing an SOP for humans -> ops/sop-create wins.
+allowed-tools: [Read, Grep, Glob, Bash, Write, Edit]
+metadata:
+  origin: arkaos
+---
+
+# Hookify — `/ops hookify`
+
+> **Agent:** Daniel (Operations Lead) | **Framework:** Correction-to-predicate compilation, warn-first enforcement
+
+A hook is a correction that stopped needing you. The third time the
+same behavior gets fixed by hand — the commit message pattern, the file
+that must never be edited directly, the command that needs a flag — the
+correction has stopped being feedback and become a specification
+nobody wrote down. This skill writes it down as executable policy.
+
+## Step 1 — Extract the predicate
+
+From the repeated correction, derive a predicate a machine can decide
+WITHOUT judgment calls:
+
+- **Good**: "Edit on `config/claude-agents/*.md` → deny (generated
+  file; the YAML is the source)."
+- **Not hookifiable**: "commit messages should be clearer" — no
+  decidable predicate. Route vague quality intents to review skills,
+  not hooks; a hook that needs judgment produces false positives that
+  teach the operator to ignore every hook.
+
+State the predicate as: *surface* (which tool calls / which moment),
+*condition* (decidable test), *action* (deny / warn / inject context).
+
+## Step 2 — Pick the surface
+
+| Surface | When it fires | Right for | House examples |
+|---|---|---|---|
+| PreToolUse (`core/hooks/pre_tool_use.py`) | before a tool call | preventing an edit/command that must not happen | frontend gate, research gate |
+| Stop (`core/hooks/stop.py`) | end of turn | measuring compliance, scoped lint over changed files | stop-lint, KB-cite check |
+| UserPromptSubmit (`config/hooks/user-prompt-submit.sh`) | before the turn | nudges and context injection, never blocking | token hygiene checks |
+
+Constraints that are not negotiable: hooks respect their timeout budget
+(UserPromptSubmit 10s, PostToolUse 5s), never block on network, exit 0
+on the non-blocking surfaces, and parse JSON with jq (python3
+fallback). A hook that exceeds its budget degrades every turn to save
+one correction — that trade is always refused.
+
+## Step 3 — Warn first, harden on evidence
+
+New enforcement ALWAYS lands warn-only with telemetry (house pattern:
+the stop-lint and frontend-gate flips). The hook logs would-block
+events to `~/.arkaos/telemetry/`; promotion to hard deny is a separate,
+deliberate change gated on the observed false-positive rate — a gate
+that fires wrongly even 1 turn in 50 gets disabled by hand and trains
+contempt for the ones that fire rightly.
+
+## Step 4 — Install with proof
+
+1. Implement on the chosen surface, following that surface's existing
+   pattern (read the sibling hooks first).
+2. Reproduce the original correction scenario and show the hook
+   catching it — a hook whose trigger was never exercised is a hope,
+   not a control.
+3. Show a benign scenario passing untouched (the false-positive probe).
+4. Register the telemetry line and, if the hook grows a flag, document
+   it where the surface's flags live.
+
+## Output
+
+```markdown
+## Hookify Report
+
+**Correction observed:** {what kept being fixed by hand, with instances}
+**Predicate:** {surface} · {condition} · {action}
+**Mode:** warn-only (telemetry: {file}) · hard-flip criterion: {rate}
+**Proof:** trigger scenario caught ✓ · benign scenario untouched ✓
+**Files:** {hook file, config, telemetry}
+```

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}
+```