arkaos 4.11.0 → 4.12.0

package/core/workflow/plan_approval.py

@@ -0,0 +1,185 @@
+"""Per-session plan-approval state machine (Interaction Reform PR3).
+
+The flow contract says Gate 2 "waits for EXPLICIT user approval", but
+nothing executable ever verified it — the enforcer only checked marker
+PRESENCE, so a bare ``[arka:routing]`` unlocked writes. This module
+tracks the missing signal:
+
+    none → presented → approved
+
+- **presented** — the Stop hook observed the turn ending at Gate 2
+  (plan shown, no Gate 3 yet).
+- **approved** — the UserPromptSubmit hook classified the NEXT user
+  message as an approval, or PostToolUse saw a successful
+  ``ExitPlanMode`` (the native plan-mode approve button IS approval).
+
+A new ``presented`` invalidates an older ``approved`` (plan B after an
+approved plan A requires fresh approval): approval is only live when
+``approved_ts >= presented_ts``.
+
+Same persistence contract as ``flow_authorization``: CWE-22-safe state
+files under ``arkaos_temp_dir`` (override ``ARKA_PLAN_APPROVAL_DIR``),
+12h TTL, never raises — hooks must not break a turn. In PR3 the
+enforcer only WARNS on missing approval (telemetry to measure false
+positives across the install base); hard deny is PR4, gated on that
+telemetry.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from core.shared.safe_session_id import safe_session_id
+from core.shared.temp_paths import arkaos_temp_dir
+
+DEFAULT_TTL_SECONDS = 12 * 60 * 60
+
+_APPROVE_RE = re.compile(
+    r"\b(aprovo|aprovado|avan[çc]a(?:m|mos)?|segue em frente|for[çc]a"
+    r"|manda|bora|go ahead|approved?|proceed|ship it|lgtm)\b",
+    re.IGNORECASE,
+)
+_REJECT_RE = re.compile(
+    r"\b(n[ãa]o|para|espera|aguarda|cancela?|stop|reject|hold)\b",
+    re.IGNORECASE,
+)
+_SHORT_YES_RE = re.compile(r"\b(sim|ok|okay|yes|yep|sure|dale)\b", re.IGNORECASE)
+
+
+def _state_dir() -> Path | None:
+    """Resolve the state dir, creating it. None when the mkdir fails.
+
+    The module's never-raises contract must hold in its OWN internals:
+    a read-only override dir or a full disk returns None (callers treat
+    it as "no state") instead of propagating an OSError into a hook
+    (QG 2026-07-09, PR4 prerequisite #3).
+    """
+    override = os.environ.get("ARKA_PLAN_APPROVAL_DIR", "").strip()
+    try:
+        if override:
+            path = Path(override)
+            path.mkdir(parents=True, exist_ok=True)
+            return path
+        return arkaos_temp_dir("arkaos-plan-approval")
+    except OSError:
+        return None
+
+
+def _state_file(session_id: str) -> Path | None:
+    safe = safe_session_id(session_id)
+    if safe is None:
+        return None
+    state_dir = _state_dir()
+    if state_dir is None:
+        return None
+    return state_dir / f"{safe}.json"
+
+
+@dataclass
+class ApprovalState:
+    state: str = "none"  # none | presented | approved
+    presented_ts: float = 0.0
+    approved_ts: float = 0.0
+    source: str = ""  # text | exit-plan-mode
+    excerpt: str = ""
+
+
+def _read(session_id: str) -> ApprovalState:
+    path = _state_file(session_id)
+    if path is None or not path.exists():
+        return ApprovalState()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return ApprovalState(**{
+            k: data.get(k, getattr(ApprovalState(), k))
+            for k in ApprovalState().__dict__
+        })
+    except Exception:  # noqa: BLE001 — corrupt state resets, never raises
+        return ApprovalState()
+
+
+def _write(session_id: str, state: ApprovalState) -> None:
+    path = _state_file(session_id)
+    if path is None:
+        return
+    try:
+        path.write_text(
+            json.dumps(asdict(state)) + "\n", encoding="utf-8"
+        )
+    except OSError:
+        return
+
+
+def mark_presented(session_id: str) -> None:
+    """The turn ended at Gate 2: a plan is on the table."""
+    state = _read(session_id)
+    state.state = "presented"
+    state.presented_ts = time.time()
+    _write(session_id, state)
+
+
+def mark_approved(
+    session_id: str, source: str = "text", excerpt: str = ""
+) -> None:
+    state = _read(session_id)
+    state.state = "approved"
+    state.approved_ts = time.time()
+    state.source = source
+    state.excerpt = excerpt[:120]
+    _write(session_id, state)
+
+
+def mark_rejected(session_id: str) -> None:
+    _write(session_id, ApprovalState())
+
+
+def get_state(session_id: str) -> ApprovalState:
+    return _read(session_id)
+
+
+def is_presented(session_id: str) -> bool:
+    state = _read(session_id)
+    return (
+        state.state in ("presented", "approved")
+        and time.time() - state.presented_ts < DEFAULT_TTL_SECONDS
+    )
+
+
+def is_approved(session_id: str) -> bool:
+    """Approval is live only when it POSTdates the latest presented plan."""
+    state = _read(session_id)
+    if state.state != "approved" or not state.approved_ts:
+        return False
+    if state.approved_ts + 0.001 < state.presented_ts:
+        return False
+    return time.time() - state.approved_ts < DEFAULT_TTL_SECONDS
+
+
+def classify_reply(text: str, has_creation_verb: bool = False) -> str:
+    """Classify a user message that follows a presented plan.
+
+    Returns "approve" | "reject" | "other". A short bare "sim/ok/yes"
+    counts as approval ONLY when unambiguous: <= 5 tokens, no creation
+    verb (a new instruction, not consent), and no question mark.
+    """
+    stripped = (text or "").strip()
+    if not stripped:
+        return "other"
+    if _REJECT_RE.search(stripped):
+        return "reject"
+    if _APPROVE_RE.search(stripped) and not has_creation_verb:
+        return "approve"
+    tokens = stripped.split()
+    if (
+        len(tokens) <= 5
+        and _SHORT_YES_RE.search(stripped)
+        and not has_creation_verb
+        and "?" not in stripped
+    ):
+        return "approve"
+    return "other"

package/departments/dev/SKILL.md

@@ -70,6 +70,16 @@ Phase 7: QUALITY GATE → Marta + Eduardo (copy) + Francisca (tech) → APPROVED
 Phase 8: DOCUMENTATION → ADR + docs to Obsidian
 ```
 
+## Codebase grounding (codebase-memory MCP)
+
+When the `codebase-memory` MCP is active in the project, consult it
+BEFORE touching complex code — in Phase 1 RESEARCH and in every
+Diagnose step: `get_architecture` for the structural map,
+`search_graph`/`get_code_snippet` to locate the real implementations,
+`trace_path` for impact analysis before a refactor. The graph is a
+PRIOR, not ground truth: verify with Read before editing. When the MCP
+is absent the phases run as before (Grep/Read exploration).
+
 ## Focused Workflow (4 Phases)
 
 For `/dev debug`, `/dev refactor`, `/dev db`, `/dev performance`, `/dev pipeline`: Diagnose → Implement with tests → Rita validates → Quality Gate (Marta).

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

@@ -44,8 +44,12 @@ The onboard flow is a 12-step pipeline, split across two reference files:
 8. Generate `PROJECT.md` in project root
 9. Register in `$ARKA_OS/projects/<name>/`
 10. Apply MCP profile — generate `.mcp.json` + `.claude/settings.local.json`
-11. Create Obsidian docs — Home, Architecture, Projects MOC, Ecosystem MOC
-12. Report — summary + next steps
+11. Index the codebase graph — when the `codebase-memory-mcp` binary
+    exists, run `codebase-memory-mcp cli index_repository
+    '{"repo_path": "<abs project path>"}'` so the consistency layer is
+    warm from day one; skip silently when the binary is absent
+12. Create Obsidian docs — Home, Architecture, Projects MOC, Ecosystem MOC
+13. Report — summary + next steps (mention the graph index status)
 
 The `ecosystem` subcommands (list/create/add) and error handling also live in mcp-config.md.
 

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

@@ -26,6 +26,13 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 
 Plan a refactoring: identify code smells, select refactoring patterns, ensure test safety net.
 
+When the `codebase-memory` MCP is active, ground the plan in the real
+structure BEFORE proposing moves: `get_architecture` for the module
+map, `trace_path` for every call-site the refactor touches (impact
+analysis), `search_graph` to find duplicated implementations worth
+consolidating. The graph is a prior — verify with Read before planning
+an edit.
+
 ## Output
 
 Refactoring plan with patterns, risk assessment, and test verification steps

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

@@ -109,6 +109,12 @@ Profile mapping:
 
 This generates `.mcp.json` and `.claude/settings.local.json`.
 
+After the profile is applied, warm the consistency layer: when the
+`codebase-memory-mcp` binary exists, run
+`codebase-memory-mcp cli index_repository '{"repo_path": "<abs path>"}'`
+so the graph is available from the first feature. Skip silently when
+the binary is absent (the sync defers the MCP entry until installed).
+
 ### Step 6: Generate PROJECT.md
 
 Create `PROJECT.md` in the project root with:

package/departments/quality/SKILL.md

@@ -23,6 +23,13 @@ override it with narrative.
 Any Department Workflow:
   ...
   Phase N-1: QUALITY GATE
+    0. Output-judge (constitution gate-judges, MEDIUM/HIGH work only):
+       one judge dispatched via the Agent tool with
+       JUDGE_VERDICT_JSON_SCHEMA (core.governance.judge), frontier
+       model, over deliverable + diff + evidence report. REVISE loops
+       the work back before the personas run (max 2); PASS findings
+       become reviewer input. Record it:
+       arka-py -m core.evals.record_cli --kind judge
     1. Run the evidence engine over the project/diff:
          ~/.arkaos/bin/arka-py -m core.governance.evidence_checks <project_dir> \
            [--changed-files f1,f2] [--test-command '...'] --json
@@ -46,6 +53,15 @@ Any Department Workflow:
        (~/.arkaos/telemetry/qg-verdicts.jsonl). Applies to EVERY review,
        not only eval runs; --eval-task-id only when the review judged a
        config/evals task.
+    7. Recipe promotion (Interaction Reform PR7, APPROVED reusable
+       features only): when the deliverable is a feature worth reusing
+       across projects (auth flow, payment integration, a standard UI
+       pattern…), PROPOSE to the operator "promote this to a recipe?".
+       On confirmation, capture it —
+       `arka-py -m core.knowledge.recipes_cli capture --spec <spec.json>`
+       (spec = {recipe, narrative, files}). Capture is fail-closed:
+       every field and file is sanitized first, refused without a
+       redaction config. Never silent — always operator-confirmed.
   Phase N: DELIVERY
     → Only reaches user after APPROVED from all three
 ```

package/installer/doctor.js

@@ -208,6 +208,13 @@ const checks = [
     check: () => graphifyDoctor().installed,
     fix: () => graphifyDoctor().hint || "Run: uv tool install graphifyy  (or pipx install graphifyy)",
   },
+  {
+    name: "codebase-memory",
+    description: "codebase-memory-mcp binary present (default consistency layer for code stacks)",
+    severity: "warn",
+    check: () => commandExists("codebase-memory-mcp"),
+    fix: () => "Install codebase-memory-mcp (see mcps/registry.json entry for the one-liner), then /arka update to activate per project",
+  },
   {
     name: "magic-api-key",
     description: "Magic API key configured (frontend UI/UX — Magic MCP)",

package/installer/index.js

@@ -372,6 +372,26 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
     console.log(`         Warning: could not seed worktree.baseRef (${err.message})`);
   }
 
+  // Interaction Reform PR1 — install the ArkaOS output style and seed
+  // it as the Claude Code default. File copy is unconditional (making
+  // the style available is not a preference); the settings seed is
+  // if-absent only — an explicit operator choice is never overridden.
+  try {
+    const { installOutputStyles, seedOutputStyleDefault } = await import("./output-style.js");
+    const styleResult = installOutputStyles({
+      sourceDir: join(ARKAOS_ROOT, "config", "output-styles"),
+    });
+    if (styleResult.copied > 0) {
+      console.log(`         ${styleResult.copied} output style(s) installed (~/.claude/output-styles/).`);
+    }
+    const seedResult = seedOutputStyleDefault({ runtime });
+    if (!seedResult.skipped && seedResult.action === "created") {
+      console.log(`         outputStyle default set to "${seedResult.value}".`);
+    }
+  } catch (err) {
+    console.log(`         Warning: could not install output style (${err.message})`);
+  }
+
   // PR43 v2.62.0 — auto-install default Claude Code plugins. Only runs
   // when runtime is Claude Code AND the `claude` CLI is available.
   // Idempotent: skips plugins already in installed_plugins.json.

package/installer/output-style.js

@@ -0,0 +1,92 @@
+// ArkaOS output style install + default seed (Interaction Reform PR1).
+//
+// The ArkaOS output style used to exist only as a hand-placed file in
+// ~/.claude/output-styles/ — orphaned from the installer, so fresh
+// installs never got the branded personality and /config showed the
+// generic default. This module makes the repo the source of truth:
+//
+//   1. Copies config/output-styles/*.md → ~/.claude/output-styles/
+//      (always — the file being available is not a preference).
+//   2. Seeds `"outputStyle": "ArkaOS"` in ~/.claude/settings.json
+//      ONLY when the key is absent. An operator who explicitly chose
+//      another style (including "default") is never overridden — the
+//      same seed-if-absent contract as worktree-baseref.js and
+//      config-seed.js.
+//
+// Never raises — failures are non-fatal install warnings.
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+
+export const DEFAULT_OUTPUT_STYLE = "ArkaOS";
+
+
+export function installOutputStyles({
+  sourceDir,
+  home = homedir(),
+} = {}) {
+  if (!sourceDir || !existsSync(sourceDir)) {
+    return { skipped: "source-not-found", copied: 0 };
+  }
+  try {
+    const destDir = join(home, ".claude", "output-styles");
+    mkdirSync(destDir, { recursive: true });
+    let copied = 0;
+    for (const name of readdirSync(sourceDir)) {
+      if (!name.endsWith(".md")) continue;
+      copyFileSync(join(sourceDir, name), join(destDir, name));
+      copied += 1;
+    }
+    return { skipped: null, copied };
+  } catch {
+    return { skipped: "copy-failed", copied: 0 };
+  }
+}
+
+
+export function seedOutputStyleDefault({
+  runtime = "claude-code",
+  home = homedir(),
+  defaultValue = DEFAULT_OUTPUT_STYLE,
+} = {}) {
+  if (runtime !== "claude-code") {
+    return { skipped: "runtime-not-claude-code", action: null };
+  }
+  const settingsPath = join(home, ".claude", "settings.json");
+  if (!existsSync(settingsPath)) {
+    return { skipped: "claude-settings-not-found", action: null };
+  }
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+  } catch {
+    return { skipped: "settings-not-parseable", action: null };
+  }
+  if (typeof settings !== "object" || settings === null) {
+    return { skipped: "settings-not-object", action: null };
+  }
+  if (typeof settings.outputStyle === "string" && settings.outputStyle) {
+    return { skipped: null, action: "noop", value: settings.outputStyle };
+  }
+  settings.outputStyle = defaultValue;
+  const tmp = `${settingsPath}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+    renameSync(tmp, settingsPath);
+  } catch {
+    // Read-only ~/.claude, disk full… — "never raises" must be true of
+    // THIS module, not delegated to caller try/catch (QG blocker M1).
+    return { skipped: "write-failed", action: null };
+  }
+  return { skipped: null, action: "created", value: defaultValue };
+}

package/installer/update.js

@@ -174,6 +174,25 @@ export async function update() {
     copyFileSync(statuslineSrc, join(installDir, "config", statuslineFile));
     console.log("         ✓ Statusline updated");
   }
+  // Interaction Reform PR1 — refresh the ArkaOS output style file and
+  // seed the default (if-absent; explicit operator choice preserved).
+  try {
+    const { installOutputStyles, seedOutputStyleDefault } = await import("./output-style.js");
+    const styleResult = installOutputStyles({
+      sourceDir: join(ARKAOS_ROOT, "config", "output-styles"),
+    });
+    if (styleResult.copied > 0) {
+      console.log("         ✓ Output style updated");
+    }
+    const seedResult = seedOutputStyleDefault({
+      runtime: manifest.runtime || "claude-code",
+    });
+    if (!seedResult.skipped && seedResult.action === "created") {
+      console.log(`         ✓ outputStyle default set to "${seedResult.value}"`);
+    }
+  } catch (err) {
+    console.log(`         ⚠ Output style update failed (${err.message})`);
+  }
 
   // ── 3. Update hooks ──
   console.log("  [3/8] Updating hooks...");

package/installer/worktree-baseref.js

@@ -51,8 +51,14 @@ export function seedWorktreeBaseRef({
   }
   settings.worktree = { ...(existing ?? {}), baseRef: defaultValue };
   const tmp = `${settingsPath}.tmp-${process.pid}`;
-  writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
-  renameSync(tmp, settingsPath);
+  try {
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+    renameSync(tmp, settingsPath);
+  } catch {
+    // Keeps the header's "never raises" claim true inside the module
+    // (QG blocker M1 parity, PR1 Interaction Reform).
+    return { skipped: "write-failed", action: null };
+  }
   return {
     skipped: null,
     action: existing ? "merged" : "created",

package/knowledge/commands-keywords.json

@@ -462,5 +462,9 @@
   "dev-spec-list": {
     "keywords": ["list specs", "show specs", "existing specs", "all specifications", "project specs"],
     "examples": ["show me all specs for this project", "list existing specifications", "what specs do we have"]
+  },
+  "arka-recipes": {
+    "keywords": ["recipe", "recipes", "receita", "reuse", "validated build", "apply recipe", "feature template"],
+    "examples": ["que receitas temos", "apply the laravel login recipe", "reusa a receita de auth"]
   }
 }

package/knowledge/commands-registry.json

@@ -1,11 +1,11 @@
 {
   "_meta": {
     "version": "3.0.0",
-    "generated": "2026-07-09T15:18:25Z",
-    "total_commands": 262,
+    "generated": "2026-07-09T19:22:12Z",
+    "total_commands": 264,
     "generator": "core/registry/generator.py",
     "departments": {
-      "arka": 19,
+      "arka": 21,
       "brand": 12,
       "community": 14,
       "content": 14,
@@ -317,6 +317,44 @@
       "requires_branch": false,
       "modifies_code": false
     },
+    {
+      "id": "arka-refine",
+      "command": "/arka refine <rough idea>",
+      "department": "arka",
+      "description": "Turn a vague or domain-unfamiliar ask into a precise English prompt by asking about the topic first (arka-refine). Auto-suggested on vague requests.",
+      "lead_agent": "arka",
+      "keywords": [],
+      "examples": [],
+      "source": "builtin",
+      "tier": 2,
+      "requires_branch": false,
+      "modifies_code": false
+    },
+    {
+      "id": "arka-recipes",
+      "command": "/arka recipes [list\\|show\\|apply] <slug>",
+      "department": "arka",
+      "description": "Reuse validated QG-approved feature builds (arka-recipes). Synapse L7.6 auto-surfaces matches.",
+      "lead_agent": "arka",
+      "keywords": [
+        "recipe",
+        "recipes",
+        "receita",
+        "reuse",
+        "validated build",
+        "apply recipe",
+        "feature template"
+      ],
+      "examples": [
+        "que receitas temos",
+        "apply the laravel login recipe",
+        "reusa a receita de auth"
+      ],
+      "source": "builtin",
+      "tier": 2,
+      "requires_branch": false,
+      "modifies_code": false
+    },
     {
       "id": "do",
       "command": "/do <description>",

package/package.json

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