arkaos 4.23.0 → 4.25.0

package/README.md

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

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.23.0 — 86 agents, 17 departments, 292 skills, 270 commands, 16 ADRs.
+> v4.25.0 — 86 agents, 17 departments, 298 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.23.0
+4.25.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. 292 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 298 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/arka/skills/conclave/SKILL.md

@@ -72,6 +72,17 @@ Your style: {communication_style}. Your framework: {decision_framework}.
 Respond in 3-5 sentences as {name} would. Be specific. Channel their actual thinking.
 ```
 
+## Independence discipline (anti-anchoring)
+
+Generate each advisor's take in an isolated context: the advisor sees the
+question and their own persona, never another advisor's answer. Anchoring
+is the failure mode this prevents — the first plausible take pulls every
+later one toward it, and ten dependent opinions collapse into one opinion
+with ten signatures. Disagreement between advisors is the signal the
+synthesis step exists to surface; only the synthesis (and the debate's
+disagreement pass) may read all ten. In `debate`, opening positions are
+likewise collected independently BEFORE the rebuttal round.
+
 ## Advisor Deep Dive: `/arka conclave advisor <name>`
 
 Full advisor profile: all 4 DNA frameworks, mental models with key questions, communication style, decision framework, sources, why matched (aligned/contrarian, score, dimension comparison).

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-node 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/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/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/evaluator-build-loop/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: dev/evaluator-build-loop
+description: >
+  Adversarial build loop for UI work: a generator implements against a
+  weighted rubric while an independent, ruthless evaluator tests the LIVE
+  app in a real browser — not the code, not screenshots — and the loop
+  repeats until the score clears the threshold. TRIGGER: "/dev
+  evaluator-build-loop", "build until it passes", "itera até passar",
+  "loop de UI", "evaluator loop", "faz e avalia até estar excelente"; any
+  UI build where the excellence-mandate visual benchmark applies and the
+  operator wants convergence without babysitting. SKIP: one-shot review
+  of an existing diff -> dev/code-review wins; UX audit of a shipped page
+  without a build loop -> dev/click-path-audit wins; writing E2E suites
+  -> dev/app-test wins.
+allowed-tools: [Read, Grep, Glob, Bash, Edit, Write]
+metadata:
+  origin: arkaos
+---
+
+# Evaluator Build Loop — `/dev evaluator-build-loop`
+
+> **Agents:** Diana (Frontend, generator) + Rita (QA, evaluator) | **Framework:** Generator–evaluator separation, rubric-driven iteration
+
+The dev server is up, the screenshot looks fine, and the agent that built
+the page declares it done. Then someone clicks the second tab, resizes to
+390px, or submits the form empty — and the illusion collapses. Builders
+grade their own work with the same eyes that produced it, which is why
+this loop never lets them. One role writes; a different role, in a fresh
+context, tries to make the page fail.
+
+## Roles — never merged, never shared
+
+| Role | Agent | Contract |
+|---|---|---|
+| **Generator** | Diana | Reads the spec + the latest `feedback-NNN.md`; fixes EVERY open finding in order — functionality → craft → design → originality; keeps the dev server alive; commits once per iteration. |
+| **Evaluator** | Rita | Fresh subagent per iteration, launched with ONLY the spec, the rubric, and the app URL — never the generator's reasoning. Drives the live app via the Playwright MCP. Scores against the rubric; writes the next `feedback-NNN.md`. |
+
+The evaluator's launch context is the mechanism, not a detail: any shared
+reasoning re-imports the generator's blind spots.
+
+## The rubric
+
+Written BEFORE iteration 1, with explicit weights, from the spec plus the
+project design system and a named visual benchmark (excellence-mandate:
+UI work loads frontend-design, ui-ux-pro-max, and the project design
+system at maximum effort). Typical weighting: functionality 40 · craft
+(states, a11y, responsiveness) 30 · design fidelity 20 · originality 10.
+A dimension the spec does not care about gets weight 0 — do not invent
+criteria mid-loop.
+
+## Evaluator discipline
+
+- Test the **live app** in the browser: click paths, keyboard, empty and
+  error states, viewport extremes. Not the code. Not screenshots.
+- Be ruthless by instruction: hunt the edge case, penalize
+  default-looking output, refuse partial credit for "almost works".
+- **Default-refuted:** when unsure whether a criterion passes, it fails.
+  Optimism is the generator's disease; the evaluator is the cure.
+- Every finding names the concrete reproduction — URL, action, expected
+  vs. observed — so the generator fixes instead of guessing.
+
+## Loop mechanics
+
+1. Generator builds iteration N; commits on the working branch; emits the
+   `[arka:design]` evidence marker (frontend gate).
+2. Evaluator (fresh context) scores the live app → `feedback-NNN.md` with
+   the score per dimension and ranked findings.
+3. Score ≥ threshold (default 90/100) → exit to Quality Gate. Otherwise
+   loop.
+4. **Circuit breaker:** 5 iterations without clearing the threshold, or
+   two consecutive iterations with no score improvement → stop and
+   escalate to the operator with the score history. Never grind silently.
+
+All handoff is by file — spec, rubric, feedback — so the loop survives a
+`/clear` and either role can be resumed cold.
+
+## Output
+
+```markdown
+## Evaluator Build Loop Report
+
+**Spec:** {path} | **Rubric threshold:** {n}
+**Iterations:** {k} | **Final score:** {score}/100
+
+| Iter | Functionality | Craft | Design | Originality | Total |
+|---|---|---|---|---|---|
+
+**Open findings:** {none, or the escalation list with reproductions}
+**Evidence:** commits {range}, feedback files, `[arka:design]` markers
+```
+
+The loop feeds the Quality Gate; it does not replace it. Marta still has
+the veto.

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 | Key-forced remounts | `key={index}` on reorderable lists, or key changing identity every render | stable identity key; component state survives reorders |
+| 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/dev/skills/spec-miner/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: dev/spec-miner
+description: >
+  Mines a spec OUT of an existing codebase: maps entry points into
+  capabilities, samples the code under an explicit token budget, and
+  emits machine-parseable WHEN→THEN requirements and invariants — with
+  uncertainty marked, nothing invented, and the source commit recorded so
+  the spec knows when it has aged. TRIGGER: "/dev spec-miner", "extrai a
+  spec", "reverse-engineer the spec", "what does this code actually do,
+  as requirements", "documenta o comportamento existente", brownfield
+  onboarding, and always BEFORE refactoring code that has no spec. SKIP:
+  spec for something new -> dev/spec wins (greenfield WHAT); a guided
+  tour of the codebase -> dev/codebase-onboard wins; library or
+  framework evaluation -> dev/research wins.
+allowed-tools: [Read, Grep, Glob, Bash, Write]
+metadata:
+  origin: arkaos
+---
+
+# Spec Miner — `/dev spec-miner`
+
+> **Agent:** Gabriel (Architect) | **Framework:** Living Specs, budgeted behavioral sampling
+
+`arka-spec` answers "what should we build?" before code exists. This
+skill answers the inverse — "what did we already build?" — for the far
+more common case: a working system whose only specification is the code
+itself, about to be refactored by someone who cannot afford to be wrong
+about current behavior.
+
+## Phase 1 — Map
+
+Detect the structure and group entry points into capabilities: HTTP
+routes, CLI commands, queued jobs, scheduled tasks, event handlers,
+public package exports. Each capability gets a name and its entry files.
+No code reading yet — this phase is inventory, and it bounds phase 2.
+
+## Phase 2 — Sample and expand, under budget
+
+Reading everything is a trap: the budget burns on utilities while the
+behavior lives at the surface. So:
+
+1. Read the entry and facade files of each capability first — in most
+   codebases they encode ~70% of observable behavior.
+2. Descend ONE level into the call chain, only where the facade defers a
+   decision (validation, branching, persistence rules).
+3. **Stop** at external boundaries (SDKs, frameworks, network) or at 15
+   files per capability, whichever comes first.
+4. Whatever was deferred is listed in the spec as explicitly unmined —
+   deferred scope is visible scope, never silent scope.
+
+## Phase 3 — Emit
+
+Requirements in WHEN→THEN form, invariants as standalone guarantees, both
+machine-parseable, written as a markdown document that sits beside the
+authored specs in `core/specs/`:
+
+```markdown
+### Requirement: {capability} — {behavior}
+WHEN {trigger and preconditions}
+THEN {observable outcome}
+<!-- source: {file}:{lines} -->
+
+### Invariant: {guarantee}
+<!-- source: {file}:{lines} -->
+```
+
+Three hard rules:
+
+- **Never invent behavior.** If the code is ambiguous, write the
+  requirement with an `<!-- uncertainty: {what is unclear} -->` marker
+  instead of a guess. A wrong spec is worse than a gap — the gap gets
+  investigated, the wrong spec gets trusted.
+- **Every claim carries a source pointer.** A requirement nobody can
+  trace to a file and line is an opinion.
+- **Stamp the mined commit hash** in the spec frontmatter. When HEAD
+  moves, the spec's age is measurable with a single
+  `git log <hash>..HEAD`, so drift is visible instead of quiet.
+
+## Output
+
+The mined spec is a markdown document beside the authored ones, and
+`status: mined` in its frontmatter is a proposed convention, not an
+engine state: it stays `mined` until a human reviews the document and
+changes the status by hand. The report ends with the coverage summary —
+capabilities mined, files read vs. deferred, uncertainty count — so the
+reader knows exactly how much of the system the spec actually saw.

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/pm/skills/epic-coordination/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: pm/epic-coordination
+description: >
+  Turns an epic into a coordinated set of GitHub issues with an explicit
+  dependency graph, then drives it: sweep for unblocked work, dispatch
+  in dependency order, keep issue state honest against merged reality,
+  and close the epic only when the graph is empty. TRIGGER: "/pm epic",
+  "break this epic into issues", "parte isto em issues", "coordena
+  estes issues", "what can start now?", "o que está desbloqueado?",
+  multi-PR work spanning more than one workstream. SKIP: sizing and
+  cadence for a sprint -> pm/sprint-plan wins; writing one story well
+  -> pm/story-write wins; branch/merge discipline within a single
+  change -> ops/github-ops wins; ranking the backlog -> pm/backlog-groom
+  wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Epic Coordination — `/pm epic`
+
+> **Agent:** Carolina (Product Manager) | **Framework:** Dependency-graph decomposition, single-source issue state
+
+An epic dies in one of two ways: as a monolith pull request nobody can
+review, or as twenty issues nobody sequenced — where three developers
+block each other by lunchtime and the "done" column fills with work
+that cannot ship because its dependency never started. Both deaths have
+the same cause: the dependencies existed, but only in someone's head.
+
+## Phase 1 — Decompose against the graph
+
+1. Break the epic into issues where each issue is **independently
+   mergeable**: it can go to master alone without breaking the build,
+   even if the feature is not yet user-visible behind it.
+2. For each issue record what it **blocks** and what it is **blocked
+   by**. A dependency that cannot be named in one sentence ("B reads
+   the schema A creates") is usually a sign the split is wrong — re-cut
+   the boundary before creating anything.
+3. Write the graph INTO the issues (`gh issue create` with "Blocked by
+   #N" / "Blocks #N" in the body, labels for the epic and workstream).
+   GitHub is the single source of state — a graph kept in a document
+   diverges from reality by the second merge.
+
+## Phase 2 — Drive by sweep
+
+Repeat until the graph is empty:
+
+1. **Sweep**: an issue is *unblocked* when every "Blocked by" reference
+   is closed AND its commits are actually on the target branch —
+   closed-but-unmerged is still blocked, whatever the issue state says.
+2. **Dispatch** every unblocked issue; independent issues run in
+   parallel, dependent ones never do.
+3. **Reconcile** after each merge: close what merged, update "Blocked
+   by" lists the merge invalidated, and re-sweep. Reality moves the
+   graph; the graph never moves reality.
+4. **Escalate stalls**: an issue unblocked for longer than the epic's
+   agreed cadence with no movement is a decision waiting to be made —
+   name it to the operator instead of letting the graph silt up.
+
+## Invariants
+
+- Every issue names its epic; the epic issue links every child. Orphan
+  work inside an epic is scope creep with a paper trail.
+- The critical path (longest dependency chain) is stated in the epic
+  issue and re-derived after every reconcile — priorities follow it,
+  not the order issues were created in.
+- Closing the epic requires the graph empty AND the epic's acceptance
+  line verified against the merged state, not against the issue list.
+
+## Output
+
+```markdown
+## Epic Status — {epic title} (#{epic issue})
+
+**Issues:** {open}/{total} · **Critical path:** #{a} → #{b} → #{c}
+**Unblocked now:** #{n}, #{m} · **Blocked:** #{x} (by #{y})
+**Stalled:** {none, or issue + the decision it waits on}
+**Next dispatch:** {what starts now, in what order, and why}
+```