arkaos 4.11.0 → 4.12.0

package/core/knowledge/recipes_cli.py

@@ -0,0 +1,99 @@
+"""Recipe capture/list/show CLI (Interaction Reform PR7).
+
+The QG skill (step 7) proposes promoting an APPROVED reusable feature
+to a recipe; on operator confirmation it calls `capture` here. Capture
+is fail-closed: no redaction config → refused (SanitizerConfigMissing),
+because a client identifier reaching the recipe corpus is the exact
+confidentiality breach the sanitizer exists to prevent.
+
+Usage:
+    arka-py -m core.knowledge.recipes_cli capture --spec <recipe.json>
+    arka-py -m core.knowledge.recipes_cli list
+    arka-py -m core.knowledge.recipes_cli show <slug>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from core.evals.sanitizer import SanitizerConfigMissing
+from core.knowledge.recipes import (
+    Recipe,
+    RecipeCaptureRefused,
+    capture_recipe,
+    list_recipes,
+    load_recipe,
+)
+
+
+def _cmd_capture(args: argparse.Namespace) -> int:
+    """Capture from a spec JSON: {recipe, narrative, files:{path:content}}."""
+    raw = (
+        Path(args.spec).read_text(encoding="utf-8")
+        if args.spec
+        else sys.stdin.read()
+    )
+    try:
+        payload = json.loads(raw)
+        recipe = Recipe.model_validate(payload["recipe"])
+    except (json.JSONDecodeError, KeyError, ValidationError) as exc:
+        print(f"error: invalid recipe spec — {exc}", file=sys.stderr)
+        return 1
+    try:
+        target = capture_recipe(
+            recipe,
+            narrative=payload.get("narrative", ""),
+            reference_files=payload.get("files", {}),
+        )
+    except SanitizerConfigMissing as exc:
+        print(f"error: capture refused — {exc}", file=sys.stderr)
+        return 2
+    except RecipeCaptureRefused as exc:
+        print(f"error: capture refused — {exc}", file=sys.stderr)
+        return 3
+    print(json.dumps({"captured": True, "slug": recipe.slug,
+                      "path": str(target)}))
+    return 0
+
+
+def _cmd_list(_args: argparse.Namespace) -> int:
+    recipes = list_recipes()
+    for recipe in recipes:
+        print(f"{recipe.slug:30s} {', '.join(recipe.stack):20s} {recipe.name}")
+    print(f"\n{len(recipes)} recipe(s)")
+    return 0
+
+
+def _cmd_show(args: argparse.Namespace) -> int:
+    recipe = load_recipe(args.slug)
+    if recipe is None:
+        print(f"error: no recipe {args.slug!r}", file=sys.stderr)
+        return 1
+    print(recipe.model_dump_json(indent=2))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_capture = sub.add_parser("capture")
+    p_capture.add_argument("--spec", help="spec JSON file (default: stdin)")
+    sub.add_parser("list")
+    p_show = sub.add_parser("show")
+    p_show.add_argument("slug")
+    args = parser.parse_args(argv)
+
+    return {
+        "capture": _cmd_capture,
+        "list": _cmd_list,
+        "show": _cmd_show,
+    }[args.cmd](args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/shared/safe_session_id.py

@@ -21,15 +21,21 @@ import re
 
 
 SAFE_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+# A token made ONLY of dots ("." / ".." / "...") passes the char
+# allowlist but is a filesystem traversal/self-reference — it must
+# reject (QG 2026-07-09: `safe_session_id('..') == '..'` would let a
+# future `recipes delete ..` rmtree ~/.arkaos).
+_DOT_ONLY_RE = re.compile(r"^\.+$")
 
 
 def safe_session_id(session_id: str) -> str | None:
     """Validate ``session_id`` against the strict allowlist.
 
     Returns the id unchanged when safe, or ``None`` when it contains
-    path separators, ``..`` traversal fragments, whitespace, unicode,
-    NUL bytes, or any character outside ``[A-Za-z0-9._-]``. Length is
-    capped at 128 characters to prevent pathological filesystem paths.
+    path separators, ``..`` traversal fragments, a dot-only token,
+    whitespace, unicode, NUL bytes, or any character outside
+    ``[A-Za-z0-9._-]``. Length is capped at 128 characters to prevent
+    pathological filesystem paths.
 
     Callers MUST treat ``None`` as reject — never construct a path or
     shell argument from the raw input when this returns ``None``.
@@ -38,4 +44,6 @@ def safe_session_id(session_id: str) -> str | None:
         return None
     if not SAFE_SESSION_ID_RE.match(session_id):
         return None
+    if _DOT_ONLY_RE.match(session_id):
+        return None
     return session_id

package/core/synapse/engine.py

@@ -204,6 +204,7 @@ def create_default_engine(
     from core.synapse.agent_experiences_layer import AgentExperiencesLayer
     from core.synapse.graph_context_layer import GraphContextLayer
     from core.synapse.pattern_library_layer import PatternLibraryLayer
+    from core.synapse.recipe_layer import RecipeLayer
 
     engine = SynapseEngine()
 
@@ -245,6 +246,11 @@ def create_default_engine(
     # specs and dispatched specialists start from prior art rather than
     # reinventing.
     engine.register_layer(PatternLibraryLayer())
+    # L7.6 (Interaction Reform PR8) — validated Recipe injection.
+    # Sibling of L7.5: surfaces QG-approved prior BUILDS (reference files
+    # on disk) when the prompt matches, so the build loop reuses proven
+    # work. Inert when no recipes are captured.
+    engine.register_layer(RecipeLayer())
     engine.register_layer(SessionContextLayer())
 
     return engine

package/core/synapse/pattern_library_layer.py

@@ -42,8 +42,12 @@ _STOPWORDS: frozenset[str] = frozenset({
 })
 
 
-def _extract_keywords(text: str, max_n: int = 10) -> list[str]:
-    """Return the first `max_n` distinct meaningful words from `text`."""
+def extract_keywords(text: str, max_n: int = 10) -> list[str]:
+    """Return the first `max_n` distinct meaningful words from `text`.
+
+    Public: shared by L7.5 (patterns) and L7.6 (recipes) — a single
+    extractor keeps the two prior-art layers matching on the same tokens.
+    """
     seen: list[str] = []
     seen_set: set[str] = set()
     for word in _WORD_RE.findall(text or ""):
@@ -57,6 +61,10 @@ def _extract_keywords(text: str, max_n: int = 10) -> list[str]:
     return seen
 
 
+# Back-compat alias (was private before Interaction Reform PR8).
+_extract_keywords = extract_keywords
+
+
 class PatternLibraryLayer(Layer):
     """L7.5 — surface prior implementations matching the user prompt."""
 

package/core/synapse/recipe_layer.py

@@ -0,0 +1,114 @@
+"""Synapse layer L7.6 — validated Recipe injection (Interaction Reform PR8).
+
+Sibling of L7.5 (Pattern Library): where a PatternCard is a short text
+hint, a Recipe points at QG-approved reference files on disk that can be
+adapted. When the prompt's keywords overlap a captured recipe, this
+layer surfaces the top matches as `[recipes:N]` so the orchestrator
+starts from "we have a validated build of this" — the `/arka refine` →
+build loop reuses proven work instead of re-deriving it.
+
+Keyword extraction is shared with L7.5 (imported, not duplicated).
+Matching is keyword-overlap on the recipe's feature_keywords + stack for
+v1; semantic ranking is a follow-up.
+"""
+
+from __future__ import annotations
+
+import time
+
+from core.knowledge.recipes import Recipe, list_recipes
+from core.synapse.layers import Layer, LayerResult, PromptContext
+from core.synapse.pattern_library_layer import extract_keywords
+
+
+class RecipeLayer(Layer):
+    """L7.6 — surface validated recipes matching the user prompt."""
+
+    def __init__(self, limit: int = 3) -> None:
+        self._limit = limit
+
+    @property
+    def id(self) -> str:
+        return "L7.6"
+
+    @property
+    def name(self) -> str:
+        return "Recipes"
+
+    @property
+    def input_sensitive(self) -> bool:
+        return True
+
+    @property
+    def cache_ttl(self) -> int:
+        return 60
+
+    @property
+    def priority(self) -> int:
+        # 76 — right after L7.5 Pattern Library (75), before L8 Forge (80),
+        # so both prior-art sources reach Forge's plan synthesis.
+        return 76
+
+    def compute(self, ctx: PromptContext) -> LayerResult:
+        start = time.time()
+        keywords = extract_keywords(ctx.user_input)
+        if not keywords:
+            return self._empty(start)
+        matches = _match_recipes(keywords, self._limit)
+        if not matches:
+            return self._empty(start, tag="[recipes:none]")
+        content = format_recipes(matches)
+        return LayerResult(
+            layer_id=self.id,
+            tag=f"[recipes:{len(matches)}]",
+            content=content,
+            tokens_est=max(1, len(content) // 4),
+            compute_ms=int((time.time() - start) * 1000),
+            cached=False,
+        )
+
+    def _empty(self, start: float, tag: str = "") -> LayerResult:
+        return LayerResult(
+            layer_id=self.id,
+            tag=tag,
+            content="",
+            tokens_est=0,
+            compute_ms=int((time.time() - start) * 1000),
+            cached=False,
+        )
+
+
+def _match_recipes(keywords: list[str], limit: int) -> list[Recipe]:
+    """Rank recipes by keyword overlap with feature_keywords + stack."""
+    kw = set(keywords)
+    scored: list[tuple[int, Recipe]] = []
+    for recipe in list_recipes():
+        haystack = {
+            w.lower()
+            for w in (recipe.feature_keywords + recipe.stack)
+        }
+        overlap = len(kw & haystack)
+        if overlap:
+            scored.append((overlap, recipe))
+    scored.sort(key=lambda pair: (-pair[0], pair[1].slug))
+    return [recipe for _, recipe in scored[:limit]]
+
+
+def format_recipes(recipes: list[Recipe]) -> str:
+    """Compact, model-readable summary pointing at the on-disk files."""
+    lines = [
+        "Validated recipes found (QG-approved prior builds — read "
+        "RECIPE.md + files/ and adapt via the normal flow, never "
+        "copy-paste blind):"
+    ]
+    for i, r in enumerate(recipes, start=1):
+        head = f"  {i}. {r.name} (~/.arkaos/recipes/{r.slug}/)"
+        if r.stack:
+            head += f" — stack: {', '.join(r.stack[:4])}"
+        lines.append(head)
+        lines.append(f"     {r.problem}")
+        if r.files:
+            lines.append(f"     files/: {', '.join(r.files[:4])}")
+        if r.apply_notes:
+            lines.append(f"     adapt: {r.apply_notes}")
+    return "\n".join(lines)

package/core/sync/mcp_optimizer.py

@@ -81,7 +81,10 @@ def _do_optimize(
 
     return mcp_result.model_copy(update={
         "final_mcp_list": sorted(active),
-        "mcps_deferred": sorted(deferred),
+        # Merge, never replace: the syncer defers entries whose
+        # requires_binary is absent (never written to .mcp.json) and
+        # that skip must survive into the report (PR6).
+        "mcps_deferred": sorted(deferred | set(mcp_result.mcps_deferred)),
         "optimizer_warnings": warnings,
     })
 

package/core/sync/mcp_syncer.py

@@ -8,22 +8,26 @@ from __future__ import annotations
 
 import copy
 import json
+import shutil
 from pathlib import Path
 
 from core.sync.schema import McpSyncResult, Project
 
 # Maps stack item names to registry categories
 _STACK_TO_CATEGORIES: dict[str, list[str]] = {
-    "laravel": ["laravel"],
-    "nuxt": ["nuxt"],
-    "vue": ["nuxt"],
-    "next": ["react"],
-    "react": ["react"],
+    "laravel": ["laravel", "grounding-code"],
+    "nuxt": ["nuxt", "grounding-code"],
+    "vue": ["nuxt", "grounding-code"],
+    "next": ["react", "grounding-code"],
+    "react": ["react", "grounding-code"],
+    "python": ["grounding-code"],
     "shopify": ["ecommerce"],
 }
 
 # Keys that are registry metadata — stripped when writing .mcp.json
-_REGISTRY_META_KEYS = {"category", "description", "required_env"}
+_REGISTRY_META_KEYS = {
+    "category", "description", "required_env", "requires_binary",
+}
 
 
 # ---------------------------------------------------------------------------
@@ -69,6 +73,39 @@ def resolve_mcps_for_stack(
     return result
 
 
+def _split_missing_binaries(
+    target: list[tuple[str, dict]],
+) -> tuple[list[tuple[str, dict]], list[str]]:
+    """Drop entries whose `requires_binary` is not on PATH.
+
+    An MCP entry pointing at an absent binary is a dead server that
+    errors on every session start — the sync never writes one. The
+    skipped names are reported (mcps_deferred) so the operator knows
+    installing the binary + re-sync activates it (Interaction Reform
+    PR6, codebase-memory-mcp).
+    """
+    available: list[tuple[str, dict]] = []
+    missing: list[str] = []
+    for name, config in target:
+        binary = config.get("requires_binary", "")
+        if binary and shutil.which(binary) is None:
+            missing.append(name)
+            continue
+        available.append((name, config))
+    return available, missing
+
+
+def _missing_binary_warnings(registry: dict, missing: list[str]) -> list[str]:
+    return [
+        (
+            f"{name}: requires binary "
+            f"'{registry.get(name, {}).get('requires_binary', '?')}' not on "
+            f"PATH — install it and re-run /arka update to activate"
+        )
+        for name in missing
+    ]
+
+
 def sync_project_mcp(
     project: Project, registry: dict, home_path: str
 ) -> McpSyncResult:
@@ -97,6 +134,7 @@ def _do_sync_mcp(
 
     current = _read_current_mcps(mcp_file)
     target_raw = resolve_mcps_for_stack(registry, project.stack)
+    target_raw, missing_binary = _split_missing_binaries(target_raw)
     target = _resolve_placeholders(target_raw, home_path, project.path)
     registry_names = set(registry.keys())
 
@@ -104,11 +142,15 @@ def _do_sync_mcp(
         current, target, registry_names, registry
     )
 
+    binary_warnings = _missing_binary_warnings(registry, missing_binary)
+
     if not added and not removed and not updated:
         return McpSyncResult(
             path=project.path,
             status="unchanged",
             final_mcp_list=sorted(current.keys()),
+            mcps_deferred=sorted(missing_binary),
+            optimizer_warnings=binary_warnings,
         )
 
     merged = _build_merged(current, target, registry_names, registry)
@@ -122,6 +164,8 @@ def _do_sync_mcp(
         mcps_removed=sorted(removed),
         mcps_updated=sorted(updated),
         mcps_preserved=sorted(preserved),
+        mcps_deferred=sorted(missing_binary),
+        optimizer_warnings=binary_warnings,
         final_mcp_list=sorted(merged.keys()),
     )
 

package/core/sync/settings_syncer.py

@@ -88,10 +88,14 @@ def _read_current_settings(settings_file: Path) -> dict:
 
 
 def _is_already_correct(current: dict, target_servers: list[str]) -> bool:
-    """Return True when servers and flag already match the target."""
+    """Return True when servers, flag and outputStyle already match."""
     current_servers = sorted(current.get("enabledMcpjsonServers", []))
     flag = current.get("enableAllProjectMcpServers", False)
-    return current_servers == target_servers and flag is True
+    return (
+        current_servers == target_servers
+        and flag is True
+        and bool(current.get("outputStyle"))
+    )
 
 
 def _compute_diff(
@@ -112,6 +116,9 @@ def _build_merged_settings(current: dict, target_servers: list[str]) -> dict:
         merged["permissions"] = _DEFAULT_PERMISSIONS
     merged["enabledMcpjsonServers"] = target_servers
     merged["enableAllProjectMcpServers"] = True
+    # Interaction Reform PR1: seed-if-absent — an explicit operator
+    # choice (any value, including "default") is never overridden.
+    merged.setdefault("outputStyle", "ArkaOS")
     return merged
 
 

package/core/workflow/flow_enforcer.py

@@ -224,6 +224,9 @@ class Decision:
     phase_observed: str | None = None
     bypass_used: bool = False
     warning: str = ""
+    # Interaction Reform PR3 — plan-approval telemetry (WARN phase):
+    # "approved" | "missing" | "no-plan" | "unknown" | "" (not gated).
+    approval_state: str = ""
 
     def to_stderr_message(self) -> str:
         if self.allow:
@@ -369,6 +372,46 @@ def _scan_markers(messages: list[str]) -> tuple[str | None, str | None]:
     return marker_found, phase_observed
 
 
+_APPROVAL_EXEMPT_REASONS: frozenset[str] = frozenset({
+    "tool-not-gated", "feature-flag-off", "env-bypass",
+    "classifier-did-not-match",
+})
+
+
+def _annotate_plan_approval(decision: Decision, session_id: str) -> Decision:
+    """PR3 WARN phase: annotate gated allows with plan-approval state.
+
+    Telemetry only — no deny path exists here (hard enforcement is PR4,
+    gated on this telemetry's false-positive rate). The stderr warning
+    fires only for the interesting case: a plan was PRESENTED and the
+    effect tool ran without the approval landing.
+    """
+    if not decision.allow or decision.reason in _APPROVAL_EXEMPT_REASONS:
+        return decision
+    if decision.marker_found == "trivial" or "trivial" in decision.reason:
+        return decision
+    try:
+        from core.workflow import plan_approval
+        if plan_approval.is_approved(session_id):
+            decision.approval_state = "approved"
+        elif plan_approval.is_presented(session_id):
+            decision.approval_state = "missing"
+            warn = (
+                "[arka:warn] no-plan-approval-warn — effect tool ran with a "
+                "presented Gate-2 plan and no user approval on record "
+                "(telemetry only in this release)."
+            )
+            decision.warning = (
+                f"{decision.warning}\n{warn}".strip()
+                if decision.warning else warn
+            )
+        else:
+            decision.approval_state = "no-plan"
+    except Exception:  # noqa: BLE001 — annotation must never break a hook
+        decision.approval_state = "unknown"
+    return decision
+
+
 def evaluate(
     tool_name: str,
     transcript_path: str,
@@ -389,7 +432,27 @@ def evaluate(
     ``messages`` (PR-6 hook consolidation): pre-parsed assistant messages.
     When None (default) the transcript is read from ``transcript_path`` —
     backward compatible with all existing callers.
+
+    Interaction Reform PR3: every gated allow is annotated with the
+    plan-approval state (``approval_state``) for the WARN-phase
+    telemetry that gates PR4's hard G2 enforcement.
     """
+    return _annotate_plan_approval(
+        _evaluate_flow(
+            tool_name, transcript_path, session_id, cwd, tool_input, messages
+        ),
+        session_id,
+    )
+
+
+def _evaluate_flow(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str = "",
+    cwd: str = "",
+    tool_input: dict | None = None,
+    messages: list[str] | None = None,
+) -> Decision:
     is_gated = tool_name in EFFECT_TOOLS_ALWAYS
     if not is_gated and tool_name == "Bash":
         bash_cmd = ""