arkaos 4.17.0 → 4.19.0

package/core/cognition/memory/schemas.py

@@ -7,12 +7,10 @@ Three core models:
 """
 
 import uuid
-from datetime import datetime, timezone
-from typing import Literal
+from datetime import UTC, datetime
 
 from pydantic import BaseModel, Field, field_validator
 
-
 # --- Allowed categories and statuses ---
 
 RAW_CAPTURE_CATEGORIES = ("decision", "solution", "pattern", "error", "config")
@@ -35,7 +33,7 @@ ACTIONABLE_INSIGHT_STATUSES = ("pending", "presented", "accepted", "dismissed")
 
 
 def _utc_now() -> datetime:
-    return datetime.now(timezone.utc)
+    return datetime.now(UTC)
 
 
 def _new_uuid() -> str:
@@ -97,8 +95,26 @@ class KnowledgeEntry(BaseModel):
         return max(0.0, min(1.0, v))
 
 
+# Instinct confidence lives in a band, never at the poles. 0.3 is a weak
+# hypothesis worth keeping; 0.9 is strong but never certainty (an agent
+# that is "certain" from a handful of observations is the failure the
+# band prevents). Follows an established continuous-learning instinct model.
+INSTINCT_CONFIDENCE_MIN = 0.3
+INSTINCT_CONFIDENCE_MAX = 0.9
+INSTINCT_SCOPES = ("project", "global")
+
+
 class ActionableInsight(BaseModel):
-    """Actionable insight — generated by agents for proactive presentation."""
+    """Actionable insight — generated by agents for proactive presentation.
+
+    Carries the instinct fields (confidence, scope,
+    evidence_count) so an insight can strengthen on corroboration, weaken
+    on contradiction, and be promoted from project to global once the
+    same signal is seen across enough projects with high enough mean
+    confidence (see ``InsightStore.promotable``). All three default to
+    backwards-compatible values, so an insight written before this schema
+    reads as a fresh, project-scoped hypothesis.
+    """
 
     id: str = Field(default_factory=_new_uuid)
     project: str
@@ -113,6 +129,30 @@ class ActionableInsight(BaseModel):
     status: str = "pending"
     presented_at: datetime | None = None
 
+    confidence: float = 0.5
+    scope: str = "project"
+    evidence_count: int = 1
+
+    @field_validator("confidence")
+    @classmethod
+    def clamp_confidence(cls, v: float) -> float:
+        """Confidence is bounded to the instinct band, never the poles."""
+        return max(INSTINCT_CONFIDENCE_MIN, min(INSTINCT_CONFIDENCE_MAX, v))
+
+    @field_validator("scope")
+    @classmethod
+    def validate_scope(cls, v: str) -> str:
+        if v not in INSTINCT_SCOPES:
+            raise ValueError(
+                f"Invalid scope '{v}'. Must be one of: {INSTINCT_SCOPES}"
+            )
+        return v
+
+    @field_validator("evidence_count")
+    @classmethod
+    def evidence_count_is_positive(cls, v: int) -> int:
+        return max(1, v)
+
     @field_validator("category")
     @classmethod
     def validate_category(cls, v: str) -> str:

package/core/hooks/pre_tool_use.py

@@ -220,6 +220,61 @@ def _frontend_gate(
     return None
 
 
+# Config edits only ever land through file_path tools. NotebookEdit
+# addresses a notebook_path, never a linter config, so it is not in the
+# set — a notebook can never be a protected config file.
+_CONFIG_GATED_TOOLS = frozenset({"Write", "Edit", "MultiEdit"})
+
+
+def _operator_messages(transcript_path: str) -> list[str]:
+    """Recent OPERATOR messages, never the agent's own — reading the
+    assistant scope would let the guarded actor authorise itself."""
+    try:
+        from core.workflow.transcript_scope import user_messages_from_path
+        return user_messages_from_path(transcript_path)
+    except Exception:
+        return []  # unreadable → no override found → fail closed
+
+
+def _config_gate(
+    root: str,
+    tool_name: str,
+    transcript_path: str,
+    tool_input: dict,
+) -> int | None:
+    """Config-protection gate. Refuses edits to linter/formatter configs
+    so the agent fixes the code instead of weakening the check. Returns 2
+    on deny (hard mode), None to continue."""
+    if tool_name not in _CONFIG_GATED_TOOLS:
+        return None
+    if not (Path(root) / "core" / "workflow" / "config_guard.py").is_file():
+        return None
+    try:
+        from core.workflow.config_guard import (
+            evaluate,
+            is_protected_config,
+            mode,
+        )
+    except Exception:
+        return None  # config-guard-import-failed → allow (chain contract)
+    # Zero-read fast path: only a protected-config edit can ever be
+    # denied, and only then is the transcript read for an override.
+    file_path = str(tool_input.get("file_path", ""))
+    if not is_protected_config(file_path):
+        return None
+    guard_mode = mode()
+    if guard_mode == "off":
+        return None
+    decision = evaluate(file_path, _operator_messages(transcript_path))
+    if decision.allow:
+        return None
+    message = decision.to_stderr_message()
+    if guard_mode == "hard":
+        return _deny(message)
+    print(message, file=sys.stderr)  # warn: surface, do not block
+    return None
+
+
 def _budget_check(session_id: str) -> tuple[bool, str]:
     """CostGovernor gate (stdlib-only). Returns (allow, warning)."""
     try:
@@ -307,6 +362,10 @@ def main(stdin_json: dict | None = None) -> int:
     if code is not None:
         return code
 
+    code = _config_gate(root, tool_name, transcript_path, tool_input)
+    if code is not None:
+        return code
+
     # Fast allow: not a flow-gated tool (Bash stays — classified per-command
     # by the enforcer via bash_is_effect()).
     if tool_name not in _FLOW_GATED_TOOLS:

package/core/provenance.py

@@ -0,0 +1,108 @@
+"""Provenance — supply-chain lineage for any ArkaOS artifact.
+
+A skill, an agent, or anything else in the tree either originates in
+ArkaOS or is derived from someone else's work. Third-party lineage is a
+security property, not trivia: a tree with no origin field cannot be
+audited after the fact, and "which licence is this under?" becomes
+unanswerable the moment the author who ported it moves on.
+
+This module owns the artifact-agnostic core — the ``Provenance`` model
+and the block validator. The file-format parsers live with the artifact
+that uses them: ``core/skills/provenance.py`` reads a SKILL.md
+frontmatter block, ``core/agents/provenance.py`` reads an agent YAML
+key. Both funnel through ``provenance_from_block`` so the validation
+rules are defined once.
+
+Rules:
+
+- ``origin`` is a lowercase slug (``^[a-z][a-z0-9-]*$``). ``arkaos`` — or
+  no block at all — is first-party and needs nothing else.
+- Any other origin MUST declare ``source`` (an https URL) and
+  ``license``. https only: a licence trail that can be MITM'd is not a
+  trail.
+- ``arkaos`` carrying a source/licence is an unresolved contradiction and
+  is rejected — silence would let a bad port keep its upstream URL while
+  claiming to be ours.
+- A block present but incoherent (unknown keys, non-mapping) is an
+  ERROR, never a silent fallback to first-party.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, Field, model_validator
+
+FIRST_PARTY = "arkaos"
+METADATA_FIELDS = ("origin", "source", "license")
+
+_ORIGIN_SLUG = re.compile(r"^[a-z][a-z0-9-]*$")
+_URL = re.compile(r"^https://\S+$")
+
+
+class ProvenanceError(ValueError):
+    """The provenance block is present but cannot be trusted."""
+
+
+class Provenance(BaseModel):
+    """Where an artifact came from, and under what licence."""
+
+    origin: str = Field(default=FIRST_PARTY)
+    source: str | None = None
+    license: str | None = None
+
+    @model_validator(mode="after")
+    def _derived_needs_a_trail(self) -> Provenance:
+        if not _ORIGIN_SLUG.match(self.origin):
+            raise ValueError(
+                f"origin {self.origin!r} is not a lowercase slug "
+                f"(^[a-z][a-z0-9-]*$)"
+            )
+        if self.origin == FIRST_PARTY:
+            return self._first_party_carries_no_trail()
+        missing = [f for f in ("source", "license") if not getattr(self, f)]
+        if missing:
+            raise ValueError(
+                f"origin {self.origin!r} is third-party — "
+                f"{', '.join(missing)} required"
+            )
+        if not _URL.match(self.source or ""):
+            raise ValueError(f"source {self.source!r} is not an https URL")
+        return self
+
+    def _first_party_carries_no_trail(self) -> Provenance:
+        """`arkaos` plus a source/licence is a contradiction.
+
+        Either the artifact is ours and there is nothing to attribute, or
+        it is not and the origin is wrong.
+        """
+        declared = [f for f in ("source", "license") if getattr(self, f)]
+        if declared:
+            raise ValueError(
+                f"origin {FIRST_PARTY!r} is first-party but declares "
+                f"{', '.join(declared)} — set a third-party origin or "
+                f"drop the field"
+            )
+        return self
+
+    @property
+    def is_first_party(self) -> bool:
+        return self.origin == FIRST_PARTY
+
+
+def provenance_from_block(block: dict | None) -> Provenance:
+    """Validate a metadata mapping into a ``Provenance``.
+
+    ``None`` (no block) is first-party. A block with keys outside
+    origin/source/license is an error — a misspelt field must not be
+    silently dropped into a first-party default.
+    """
+    if block is None:
+        return Provenance()
+    unknown = sorted(str(k) for k in block if k not in METADATA_FIELDS)
+    if unknown:
+        raise ProvenanceError(
+            f"unknown metadata keys: {', '.join(unknown)} "
+            f"(expected {', '.join(METADATA_FIELDS)})"
+        )
+    return Provenance(**block)

package/core/skills/provenance.py

@@ -9,18 +9,18 @@ author who ported it moves on.
 Contract (opt-in, absence means first-party):
 
     ---
-    name: dev/silent-failure-hunter
+    name: dev/example-skill
     description: ...
     allowed-tools: [Read, Grep, Glob]
     metadata:
-      origin: ecc-derived
-      source: https://github.com/affaan-m/ecc
+      origin: vendor-derived
+      source: https://example.com/upstream
       license: MIT
     ---
 
 ``origin`` is a lowercase slug (``^[a-z][a-z0-9-]*$``). ``arkaos`` — or
 no metadata block at all — is first-party and needs nothing else. ANY
-other origin MUST declare ``source`` (an http(s) URL) and ``license``.
+other origin MUST declare ``source`` (an https URL) and ``license``.
 
 **Fail closed.** A block that is present but unusable — unparseable
 YAML, a tab-indented body, ``metadata`` bound to a scalar, a misspelt
@@ -40,6 +40,12 @@ module cannot enforce that and does not claim to.
 Consumed by ``scripts/skill_validator.py`` (per-skill score) and
 ``scripts/marketplace_gen.py`` (``knowledge/skills-manifest.json``,
 which carries the full origin/source/licence triple, not just origin).
+
+The artifact-agnostic core — the model, the constants, the block
+validator — lives in ``core/provenance.py`` and is shared with agent
+provenance (``core/agents/provenance.py``). This module is only the
+SKILL.md-frontmatter reader. ``SkillProvenance`` is re-exported as an
+alias of the generic ``Provenance`` so existing imports keep working.
 """
 
 from __future__ import annotations
@@ -47,70 +53,35 @@ from __future__ import annotations
 import re
 
 import yaml
-from pydantic import BaseModel, Field, ValidationError, model_validator
-
-FIRST_PARTY = "arkaos"
-METADATA_FIELDS = ("origin", "source", "license")
+from pydantic import ValidationError
+
+from core.provenance import (
+    FIRST_PARTY,
+    METADATA_FIELDS,
+    Provenance,
+    ProvenanceError,
+    provenance_from_block,
+)
+
+# Back-compat alias: a skill's provenance is just Provenance.
+SkillProvenance = Provenance
+
+__all__ = [
+    "FIRST_PARTY",
+    "METADATA_FIELDS",
+    "Provenance",
+    "ProvenanceError",
+    "SkillProvenance",
+    "declares_provenance",
+    "parse_provenance",
+    "provenance_issues",
+]
 
 _FRONTMATTER = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
-_ORIGIN_SLUG = re.compile(r"^[a-z][a-z0-9-]*$")
-# https only: a licence trail that can be MITM'd is not a trail.
-_URL = re.compile(r"^https://\S+$")
 # Near-misses for `metadata` — a typo must not read as "no block".
 _METADATA_TYPO = re.compile(r"^meta[-_ ]?datas?$", re.IGNORECASE)
 
 
-class ProvenanceError(ValueError):
-    """The provenance block is present but cannot be trusted."""
-
-
-class SkillProvenance(BaseModel):
-    """Where a skill came from, and under what licence."""
-
-    origin: str = Field(default=FIRST_PARTY)
-    source: str | None = None
-    license: str | None = None
-
-    @model_validator(mode="after")
-    def _derived_needs_a_trail(self) -> SkillProvenance:
-        if not _ORIGIN_SLUG.match(self.origin):
-            raise ValueError(
-                f"origin {self.origin!r} is not a lowercase slug "
-                f"(^[a-z][a-z0-9-]*$)"
-            )
-        if self.origin == FIRST_PARTY:
-            return self._first_party_carries_no_trail()
-        missing = [f for f in ("source", "license") if not getattr(self, f)]
-        if missing:
-            raise ValueError(
-                f"origin {self.origin!r} is third-party — "
-                f"{', '.join(missing)} required"
-            )
-        if not _URL.match(self.source or ""):
-            raise ValueError(f"source {self.source!r} is not an https URL")
-        return self
-
-    def _first_party_carries_no_trail(self) -> SkillProvenance:
-        """`arkaos` plus a source/licence is an unresolved contradiction.
-
-        Either the skill is ours and there is nothing to attribute, or
-        it is not and the origin is wrong. Silence would let a bad port
-        keep its upstream URL while claiming to be first-party.
-        """
-        declared = [f for f in ("source", "license") if getattr(self, f)]
-        if declared:
-            raise ValueError(
-                f"origin {FIRST_PARTY!r} is first-party but declares "
-                f"{', '.join(declared)} — set a third-party origin or "
-                f"drop the field"
-            )
-        return self
-
-    @property
-    def is_first_party(self) -> bool:
-        return self.origin == FIRST_PARTY
-
-
 def _frontmatter(content: str) -> dict:
     """The YAML frontmatter mapping. Raises when present but broken."""
     match = _FRONTMATTER.match(content)
@@ -157,16 +128,7 @@ def parse_provenance(content: str) -> SkillProvenance:
     present but incoherent — callers that must not raise use
     ``provenance_issues`` instead.
     """
-    block = _metadata_block(_frontmatter(content))
-    if block is None:
-        return SkillProvenance()
-    unknown = sorted(str(k) for k in block if k not in METADATA_FIELDS)
-    if unknown:
-        raise ProvenanceError(
-            f"unknown metadata keys: {', '.join(unknown)} "
-            f"(expected {', '.join(METADATA_FIELDS)})"
-        )
-    return SkillProvenance(**block)
+    return provenance_from_block(_metadata_block(_frontmatter(content)))
 
 
 def declares_provenance(content: str) -> bool:

package/core/workflow/config_guard.py

@@ -0,0 +1,176 @@
+"""Config-protection gate — the agent fixes the code, not the linter.
+
+An agent that hits a lint or type error has two ways out: fix the code,
+or edit the config so the check stops firing. The second is faster and
+almost always wrong — it silences the signal for the whole team, not
+just this change. This gate is the cheapest high-value control in the
+set: refuse edits to linter/formatter/type-checker configs, and the
+agent is left with the honest path.
+
+This is a PreToolUse gate. It denies a Write/Edit to a protected config
+file and tells the agent to fix the underlying code instead. Two escape
+hatches, because the rule is a heuristic and the operator is in charge:
+
+- ``ARKA_BYPASS_CONFIG_GUARD=1`` in the environment — a deliberate,
+  auditable override for the sessions where editing the config IS the
+  task (bumping a rule set, adopting a new formatter).
+- an explicit instruction in a recent USER message that names the config
+  file — if the operator asked for it, the agent is not sneaking around a
+  check, it is doing what it was told.
+
+The override reads the operator's messages, never the agent's. Reading
+the agent's own turns would invert the control: the guarded actor could
+authorise its own edit by naming the file, while the operator's real
+request went unseen. The user-message source is the whole point.
+
+Failure directions, chosen deliberately:
+- The GATE CHAIN degrades open on infrastructure failure (missing module,
+  import error) — a broken guard must not block all edits.
+- The OVERRIDE fails closed: when the operator's intent cannot be read
+  (no transcript, unreadable), the edit is treated as unauthorised and
+  denied in hard mode. The env bypass is the escape hatch that never
+  depends on the transcript, so a locked-out operator is never stuck.
+
+Feature-flagged off by default via ``hooks.configGuard`` (off | warn |
+hard) until telemetry says promote.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
+
+# Config files whose whole purpose is to define a quality bar. Matched on
+# the basename, case-insensitively. A change here weakens the check for
+# everyone, so the agent must not reach for it to get unblocked.
+_PROTECTED_BASENAMES = frozenset({
+    # JS/TS linters & formatters
+    ".eslintrc", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json",
+    ".eslintrc.yml", ".eslintrc.yaml", "eslint.config.js",
+    "eslint.config.mjs", "eslint.config.cjs", ".prettierrc",
+    ".prettierrc.json", ".prettierrc.js", ".prettierrc.yml",
+    ".prettierrc.yaml", "prettier.config.js", "biome.json", "biome.jsonc",
+    ".editorconfig",
+    # Python
+    "ruff.toml", ".ruff.toml", ".flake8", ".pylintrc", "mypy.ini",
+    ".mypy.ini", ".pre-commit-config.yaml",
+    # PHP / Ruby / Go / Rust
+    ".php-cs-fixer.php", ".php-cs-fixer.dist.php", "phpstan.neon",
+    "phpstan.neon.dist", "psalm.xml", ".rubocop.yml", ".golangci.yml",
+    ".golangci.yaml", "rustfmt.toml", ".rustfmt.toml", "clippy.toml",
+})
+# Files that CARRY tool config among other things — protect only the
+# lint/format/type sections conceptually, but at the file level we can
+# only warn, not know. These are NOT hard-denied (they hold real project
+# config too); they are left to the operator. Documented, not enforced:
+#   pyproject.toml, package.json, setup.cfg, tox.ini
+# The basename set above is deliberately the "config IS the check" tier.
+
+_ENV_BYPASS = "ARKA_BYPASS_CONFIG_GUARD"
+
+
+def mode() -> str:
+    """Resolve ``hooks.configGuard`` to 'off' | 'warn' | 'hard'.
+
+    Default 'warn': the gate observes and nudges but never blocks, so it
+    ships dark and earns 'hard' on telemetry (the frontend-gate and
+    specialist-gate rollout pattern). Unreadable config degrades to
+    'warn', never to 'hard' — a guard must not start blocking because a
+    file failed to parse.
+    """
+    if not CONFIG_PATH.exists():
+        return "warn"
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return "warn"
+    raw = data.get("hooks", {}).get("configGuard", "warn")
+    if raw in (False, "off", "false"):
+        return "off"
+    if raw in (True, "hard", "true"):
+        return "hard"
+    return "warn"
+
+
+@dataclass(frozen=True)
+class ConfigGuardDecision:
+    """Allow or deny, with the reason on record."""
+
+    allow: bool
+    reason: str = ""
+    file_path: str = ""
+
+    def to_stderr_message(self) -> str:
+        if self.allow:
+            return ""
+        return (
+            f"[arka:config-guard] Refusing to edit {self.file_path}. That "
+            f"file defines the quality bar; editing it to clear a lint, "
+            f"type, or format error silences the check for the whole team "
+            f"instead of fixing the code. Fix the underlying code.\n"
+            f"To lift this, the OPERATOR must name {self.file_path} in a "
+            f"message (an agent cannot authorise its own config edit), or "
+            f"set {_ENV_BYPASS}=1 in the environment."
+        )
+
+
+def is_protected_config(file_path: str) -> bool:
+    """Whether a path is a config file whose edit weakens a check."""
+    if not file_path:
+        return False
+    return Path(file_path).name.lower() in _PROTECTED_BASENAMES
+
+
+def _operator_named_file(
+    user_messages: list[str] | None, file_path: str
+) -> bool:
+    """Did the OPERATOR name this config file in a recent message?
+
+    The whole basename must appear as its own token. The trailing guard
+    blocks a sibling file — ``ruff.toml.bak``, ``ruff.toml~``,
+    ``ruff.toml-old`` must not authorise an edit to ``ruff.toml`` — while
+    still allowing a sentence-ending period (``edit ruff.toml.`` should
+    match): the negative lookahead fires on a dot/tilde/hyphen only when
+    it continues into a filename, not on end punctuation. Case-insensitive
+    to match ``is_protected_config``, which lowercases the basename.
+    """
+    if not user_messages or not file_path:
+        return False
+    name = re.escape(Path(file_path).name)
+    pattern = re.compile(
+        rf"(?<![\w.]){name}(?![\w])(?!\.\w)(?![~-])", re.IGNORECASE
+    )
+    return any(
+        pattern.search(m) for m in user_messages if isinstance(m, str)
+    )
+
+
+def evaluate(
+    file_path: str,
+    user_messages: list[str] | None = None,
+) -> ConfigGuardDecision:
+    """Decide whether to allow an edit to a protected config file.
+
+    Allows everything that is not a protected config; denies a protected
+    config edit unless the env bypass is set or the OPERATOR named the
+    file in a recent message. ``user_messages`` must be operator turns —
+    passing the agent's own messages inverts the control.
+    """
+    if not is_protected_config(file_path):
+        return ConfigGuardDecision(allow=True)
+    if os.environ.get(_ENV_BYPASS) == "1":
+        return ConfigGuardDecision(
+            allow=True, reason="env-bypass", file_path=file_path
+        )
+    if _operator_named_file(user_messages, file_path):
+        return ConfigGuardDecision(
+            allow=True, reason="operator-named-file", file_path=file_path
+        )
+    return ConfigGuardDecision(
+        allow=False, reason="protected-config", file_path=file_path
+    )

package/core/workflow/transcript_scope.py

@@ -72,3 +72,49 @@ def split_from_path(transcript_path: str) -> ScopeSplit:
     except OSError:
         return ScopeSplit()
     return split_by_scope(raw)
+
+
+def recent_user_messages(raw_text: str, limit: int = 6) -> list[str]:
+    """The most recent USER message texts, newest last.
+
+    ``split_by_scope`` collects assistant records only. A gate that must
+    know what the OPERATOR asked — not what the agent said — needs the
+    other role, and reading the wrong one inverts the gate: the guarded
+    agent could authorise its own edit while the operator's real request
+    is never seen. Sidechain (subagent) user turns are excluded — a
+    dispatched agent's prompt is not the operator speaking.
+    """
+    found: list[str] = []
+    for line in raw_text.splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(record, dict):
+            continue
+        message = record.get("message")
+        message = message if isinstance(message, dict) else {}
+        role = record.get("role") or message.get("role")
+        if role != "user" or record.get("isSidechain", False):
+            continue
+        content = record.get("content")
+        if content is None:
+            content = message.get("content")
+        text = _extract_text(content)
+        if text:
+            found.append(text)
+    return found[-limit:]
+
+
+def user_messages_from_path(transcript_path: str, limit: int = 6) -> list[str]:
+    """Recent operator messages from a transcript file. Never raises."""
+    path = Path(transcript_path) if transcript_path else None
+    if path is None or not path.exists():
+        return []
+    try:
+        raw = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+    return recent_user_messages(raw, limit)