arkaos 4.17.0 → 4.18.0

package/README.md

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

package/VERSION

@@ -1 +1 @@
-4.17.0
+4.18.0

package/arka/SKILL.md

@@ -25,7 +25,7 @@ measures citation compliance per turn.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 86 agents. 17 departments. 275 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 279 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/config/agents-provenance.yaml

@@ -0,0 +1,126 @@
+# Agent provenance classification — the control that makes omission impossible.
+#
+# Mirror of config/skills-provenance.yaml for the agent tree. The parser
+# (core/agents/provenance.py) closes every way of writing a BROKEN
+# provenance block, but it cannot see an agent that never writes one:
+# absence reads as first-party, which is exactly what a forgotten ECC
+# agent port looks like.
+#
+# EVERY agent YAML must be CLASSIFIED — listed in `first_party` below,
+# listed in `derived` below, or declaring a `provenance:` block in its
+# own YAML. An agent in none of the three fails CI by name.
+# See tests/python/test_agent_provenance.py.
+#
+# `first_party` is the baseline: the agents that existed on the cut date,
+# snapshotted once so they need no edits. CLOSED set — do not add to it.
+# A new agent declares its origin in its own YAML; a ported one lands in
+# `derived` with its licence written down, in a diff, in front of a
+# reviewer.
+#
+# What the baseline is and is not:
+#   ASSERTED: these are ArkaOS originals.
+#   PROVEN: none can be ECC-derived — every one was created before
+#     2026-07-14, the day we first read that repository (git log
+#     --diff-filter=A; verified once).
+#   The property the control rests on is that the set is CLOSED:
+#     anything new must classify itself.
+#
+# Keys are repo-relative agent YAML paths.
+#
+# derived format:
+#   departments/<dept>/agents/<slug>.yaml:
+#     origin: <lowercase-slug>      # e.g. ecc-derived, community
+#     source: https://...
+#     license: MIT
+
+baseline_date: 2026-07-14
+
+derived: {}
+
+first_party:
+  - departments/brand/agents/brand-director.yaml
+  - departments/brand/agents/brand-strategist.yaml
+  - departments/brand/agents/design-ops/design-ops-lead.yaml
+  - departments/brand/agents/design-ops/extraction-script-writer.yaml
+  - departments/brand/agents/design-ops/shadcn-padronizer.yaml
+  - departments/brand/agents/design-ops/wcag-auditor.yaml
+  - departments/brand/agents/ux-designer.yaml
+  - departments/brand/agents/ux-researcher.yaml
+  - departments/brand/agents/ux-strategist.yaml
+  - departments/brand/agents/visual-designer.yaml
+  - departments/community/agents/community-manager.yaml
+  - departments/community/agents/community-strategist.yaml
+  - departments/community/agents/engagement-designer.yaml
+  - departments/content/agents/content-strategist.yaml
+  - departments/content/agents/production/content-researcher.yaml
+  - departments/content/agents/production/info-compiler.yaml
+  - departments/content/agents/production/trends-analyst.yaml
+  - departments/content/agents/production/video-producer.yaml
+  - departments/content/agents/repurpose-distributor.yaml
+  - departments/content/agents/scriptwriter.yaml
+  - departments/content/agents/viral-engineer.yaml
+  - departments/dev/agents/ai-engineering/ai-engineering-lead.yaml
+  - departments/dev/agents/architect.yaml
+  - departments/dev/agents/backend-core/laravel-eng.yaml
+  - departments/dev/agents/backend-core/node-ts-eng.yaml
+  - departments/dev/agents/backend-core/python-eng.yaml
+  - departments/dev/agents/backend-dev.yaml
+  - departments/dev/agents/cto.yaml
+  - departments/dev/agents/data-platform/etl-eng.yaml
+  - departments/dev/agents/dba.yaml
+  - departments/dev/agents/devops-eng.yaml
+  - departments/dev/agents/frontend-dev.yaml
+  - departments/dev/agents/qa-eng.yaml
+  - departments/dev/agents/research-assistant.yaml
+  - departments/dev/agents/security-eng.yaml
+  - departments/dev/agents/tech-lead.yaml
+  - departments/ecom/agents/commerce-engineer.yaml
+  - departments/ecom/agents/cro-specialist.yaml
+  - departments/ecom/agents/ecom-director.yaml
+  - departments/ecom/agents/retention-manager.yaml
+  - departments/finance/agents/cfo.yaml
+  - departments/finance/agents/financial-analyst.yaml
+  - departments/finance/agents/investment-strategist.yaml
+  - departments/kb/agents/data-collector.yaml
+  - departments/kb/agents/knowledge-curator.yaml
+  - departments/kb/agents/knowledge-director.yaml
+  - departments/kb/agents/research-analyst.yaml
+  - departments/landing/agents/affiliate-manager.yaml
+  - departments/landing/agents/conversion-strategist.yaml
+  - departments/landing/agents/cro-specialist.yaml
+  - departments/landing/agents/sales-copywriter.yaml
+  - departments/leadership/agents/culture-coach.yaml
+  - departments/leadership/agents/hr-specialist.yaml
+  - departments/leadership/agents/leadership-director.yaml
+  - departments/marketing/agents/content-marketer.yaml
+  - departments/marketing/agents/marketing-director.yaml
+  - departments/marketing/agents/paid-specialist.yaml
+  - departments/marketing/agents/seo-specialist.yaml
+  - departments/ops/agents/automation-engineer.yaml
+  - departments/ops/agents/doc-writer.yaml
+  - departments/ops/agents/ops-lead.yaml
+  - departments/org/agents/chief-of-staff.yaml
+  - departments/org/agents/coo.yaml
+  - departments/org/agents/okr-steward.yaml
+  - departments/org/agents/org-designer.yaml
+  - departments/org/agents/people-ops.yaml
+  - departments/pm/agents/pm-director.yaml
+  - departments/pm/agents/product-owner.yaml
+  - departments/pm/agents/scrum-master.yaml
+  - departments/pm/agents/strategic-pm.yaml
+  - departments/quality/agents/copy-director.yaml
+  - departments/quality/agents/cqo.yaml
+  - departments/quality/agents/tech-director.yaml
+  - departments/saas/agents/cs-manager.yaml
+  - departments/saas/agents/growth-engineer.yaml
+  - departments/saas/agents/metrics-analyst.yaml
+  - departments/saas/agents/revops-lead.yaml
+  - departments/saas/agents/saas-strategist.yaml
+  - departments/sales/agents/sales-closer.yaml
+  - departments/sales/agents/sales-director.yaml
+  - departments/sales/agents/sales-ops.yaml
+  - departments/sales/agents/sdr.yaml
+  - departments/strategy/agents/business-model-designer.yaml
+  - departments/strategy/agents/decision-quality.yaml
+  - departments/strategy/agents/market-analyst.yaml
+  - departments/strategy/agents/strategy-director.yaml

package/config/skills-provenance.yaml

@@ -58,7 +58,26 @@
 
 baseline_date: 2026-07-14
 
-derived: {}
+derived:
+  # ECC review lenses (Track C1) — specialised review skills ArkaOS
+  # lacked, ported from the MIT-licensed everything-claude-code repo and
+  # rewritten in ArkaOS voice with ArkaOS personas.
+  departments/dev/skills/silent-failure-hunter:
+    origin: ecc-derived
+    source: https://github.com/affaan-m/ecc
+    license: MIT
+  departments/dev/skills/type-design-analyzer:
+    origin: ecc-derived
+    source: https://github.com/affaan-m/ecc
+    license: MIT
+  departments/dev/skills/pr-test-analyzer:
+    origin: ecc-derived
+    source: https://github.com/affaan-m/ecc
+    license: MIT
+  departments/dev/skills/click-path-audit:
+    origin: ecc-derived
+    source: https://github.com/affaan-m/ecc
+    license: MIT
 
 first_party:
   - arka

package/core/agents/provenance.py

@@ -0,0 +1,117 @@
+"""Agent provenance — supply-chain lineage for every agent YAML.
+
+The skill tree got provenance in v4.17.0; agents did not, and the ECC
+teardown puts ~15 derived agents on the roadmap. An ECC agent ported
+today would land with exactly the hole skill provenance closes: no
+origin, no licence trail, indistinguishable from an ArkaOS original.
+This is the agent-side mirror, and it must land before the first agent
+port.
+
+An agent YAML may carry a top-level ``provenance`` block:
+
+    id: silent-failure-hunter
+    name: ...
+    provenance:
+      origin: ecc-derived
+      source: https://github.com/affaan-m/ecc
+      license: MIT
+
+Absent means first-party. The validation rules are the shared
+``core.provenance`` core (https source, licence required for derived,
+no trail on ``arkaos``). This module only reads the YAML.
+
+As with skills, no parser can see the omission vector — a port that
+never writes the block reads as first-party. ``config/agents-provenance.yaml``
+classifies every agent as baseline, derived, or self-declaring, and
+``tests/python/test_agent_provenance.py`` fails CI on any agent that is
+none of the three.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from core.provenance import (
+    FIRST_PARTY,
+    Provenance,
+    ProvenanceError,
+    provenance_from_block,
+)
+
+__all__ = [
+    "FIRST_PARTY",
+    "Provenance",
+    "ProvenanceError",
+    "agent_provenance",
+    "declares_provenance",
+    "provenance_from_yaml",
+    "provenance_issues_from_yaml",
+]
+
+
+def _provenance_block(data: dict) -> dict | None:
+    """The ``provenance`` mapping from a loaded agent YAML.
+
+    Present-but-not-a-mapping is an error, never a silent first-party
+    fallback — the same fail-closed rule the skill parser uses.
+    """
+    if "provenance" not in data:
+        return None
+    block = data["provenance"]
+    if not isinstance(block, dict):
+        raise ProvenanceError(
+            "provenance must be a mapping of origin/source/license"
+        )
+    return block
+
+
+def provenance_from_yaml(data: dict) -> Provenance:
+    """Parse the provenance of a loaded agent YAML mapping.
+
+    Raises ``ProvenanceError``/``ValidationError`` when the block is
+    present but incoherent.
+    """
+    if not isinstance(data, dict):
+        raise ProvenanceError("agent YAML is not a mapping")
+    return provenance_from_block(_provenance_block(data))
+
+
+def declares_provenance(data: dict) -> bool:
+    """Did the author WRITE a provenance block? (vs the first-party
+    default). The classification control needs this distinction, which
+    ``provenance_from_yaml`` collapses."""
+    if not isinstance(data, dict):
+        return False
+    try:
+        return _provenance_block(data) is not None
+    except ProvenanceError:
+        return True  # broken but attempted
+
+
+def _load_yaml(path: Path) -> dict:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as exc:
+        raise ProvenanceError(f"{path}: cannot read agent YAML — {exc}") from exc
+    return data if isinstance(data, dict) else {}
+
+
+def agent_provenance(path: str | Path) -> Provenance:
+    """Provenance of an agent YAML file. Raises on an incoherent block."""
+    return provenance_from_yaml(_load_yaml(Path(path)))
+
+
+def provenance_issues_from_yaml(data: dict) -> list[str]:
+    """Non-raising validation of a loaded agent YAML. Empty = clean."""
+    from pydantic import ValidationError
+    try:
+        provenance_from_yaml(data)
+    except ProvenanceError as exc:
+        return [str(exc)]
+    except ValidationError as exc:
+        return [
+            err["msg"].removeprefix("Value error, ") for err in exc.errors()
+        ]
+    return []

package/core/agents/registry_gen.py

@@ -11,6 +11,77 @@ from datetime import datetime
 from pathlib import Path
 
 from core.agents.loader import load_agent
+from core.agents.provenance import Provenance, agent_provenance
+
+
+def _provenance_entry(prov: Provenance) -> dict:
+    """The full origin/source/licence trail for the registry — not just
+    origin, so the shipped file can answer 'what licence is this under?'."""
+    entry = {"origin": prov.origin}
+    if not prov.is_first_party:
+        entry["source"] = prov.source
+        entry["license"] = prov.license
+    return entry
+
+
+def _dna_dict(dna) -> dict:
+    """The four-framework behavioral DNA, flattened for the registry."""
+    return {
+        "disc": {
+            "primary": dna.disc.primary.value,
+            "secondary": dna.disc.secondary.value,
+            "label": dna.disc.label,
+        },
+        "enneagram": {
+            "type": dna.enneagram.type.value,
+            "wing": dna.enneagram.wing,
+            "label": dna.enneagram.label,
+        },
+        "big_five": {
+            "O": dna.big_five.openness,
+            "C": dna.big_five.conscientiousness,
+            "E": dna.big_five.extraversion,
+            "A": dna.big_five.agreeableness,
+            "N": dna.big_five.neuroticism,
+        },
+        "mbti": dna.mbti.type.value,
+    }
+
+
+def _agent_entry(agent, prov: Provenance, yaml_file: Path, root: Path) -> dict:
+    """One registry entry for a loaded agent + its provenance."""
+    return {
+        "id": agent.id,
+        "name": agent.name,
+        "role": agent.role,
+        "department": agent.department,
+        "tier": agent.tier,
+        "model": agent.get_model(),
+        "provenance": _provenance_entry(prov),
+        "parent_squad": agent.parent_squad,
+        "sub_squad_role": agent.sub_squad_role,
+        **_dna_dict(agent.behavioral_dna),
+        "authority": {
+            k: v for k, v in agent.authority.model_dump().items()
+            if v and v != [] and k not in ("delegates_to", "escalates_to")
+        },
+        "expertise_domains": agent.expertise.domains,
+        "frameworks": agent.expertise.frameworks,
+        "knowledge_sources": agent.expertise.knowledge_sources,
+        "file": str(yaml_file.relative_to(root)),
+        "memory_path": agent.memory_path,
+    }
+
+
+def _summaries(agents: list[dict]) -> dict:
+    """Tier, department, and DISC-primary counts for the registry meta."""
+    tiers, depts, disc = {}, {}, {}
+    for a in agents:
+        tiers[a["tier"]] = tiers.get(a["tier"], 0) + 1
+        depts[a["department"]] = depts.get(a["department"], 0) + 1
+        primary = a["disc"]["primary"]
+        disc[primary] = disc.get(primary, 0) + 1
+    return {"tiers": tiers, "departments": depts, "disc_distribution": disc}
 
 
 def generate_registry(departments_dir: str | Path, output_path: str | Path) -> dict:
@@ -34,72 +105,19 @@ def generate_registry(departments_dir: str | Path, output_path: str | Path) -> d
     for yaml_file in sorted(departments_dir.glob("*/agents/**/*.yaml")):
         try:
             agent = load_agent(yaml_file)
-            entry = {
-                "id": agent.id,
-                "name": agent.name,
-                "role": agent.role,
-                "department": agent.department,
-                "tier": agent.tier,
-                "model": agent.get_model(),
-                "parent_squad": agent.parent_squad,
-                "sub_squad_role": agent.sub_squad_role,
-                "disc": {
-                    "primary": agent.behavioral_dna.disc.primary.value,
-                    "secondary": agent.behavioral_dna.disc.secondary.value,
-                    "label": agent.behavioral_dna.disc.label,
-                },
-                "enneagram": {
-                    "type": agent.behavioral_dna.enneagram.type.value,
-                    "wing": agent.behavioral_dna.enneagram.wing,
-                    "label": agent.behavioral_dna.enneagram.label,
-                },
-                "big_five": {
-                    "O": agent.behavioral_dna.big_five.openness,
-                    "C": agent.behavioral_dna.big_five.conscientiousness,
-                    "E": agent.behavioral_dna.big_five.extraversion,
-                    "A": agent.behavioral_dna.big_five.agreeableness,
-                    "N": agent.behavioral_dna.big_five.neuroticism,
-                },
-                "mbti": agent.behavioral_dna.mbti.type.value,
-                "authority": {
-                    k: v for k, v in agent.authority.model_dump().items()
-                    if v and v != [] and k not in ("delegates_to", "escalates_to")
-                },
-                "expertise_domains": agent.expertise.domains,
-                "frameworks": agent.expertise.frameworks,
-                "knowledge_sources": agent.expertise.knowledge_sources,
-                "file": str(yaml_file.relative_to(departments_dir.parent)),
-                "memory_path": agent.memory_path,
-            }
-            agents.append(entry)
+            prov = agent_provenance(yaml_file)
+            agents.append(_agent_entry(
+                agent, prov, yaml_file, departments_dir.parent))
         except Exception as e:
             errors.append(f"{yaml_file.name}: {e}")
 
-    # Build tier summary
-    tier_counts = {}
-    for a in agents:
-        tier_counts[a["tier"]] = tier_counts.get(a["tier"], 0) + 1
-
-    # Build department summary
-    dept_counts = {}
-    for a in agents:
-        dept_counts[a["department"]] = dept_counts.get(a["department"], 0) + 1
-
-    # Build DISC distribution
-    disc_counts = {}
-    for a in agents:
-        p = a["disc"]["primary"]
-        disc_counts[p] = disc_counts.get(p, 0) + 1
-
     registry = {
         "_meta": {
             "version": "2.0.0",
             "generated": datetime.now().isoformat(),
             "total_agents": len(agents),
             "generator": "core/agents/registry_gen.py",
-            "tiers": tier_counts,
-            "departments": dept_counts,
-            "disc_distribution": disc_counts,
+            **_summaries(agents),
         },
         "agents": agents,
     }

package/core/cognition/insights/store.py

@@ -5,10 +5,14 @@ project filtering, presentation lifecycle, and dismissal analytics.
 """
 
 import sqlite3
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 
-from core.cognition.memory.schemas import ActionableInsight
+from core.cognition.memory.schemas import (
+    INSTINCT_CONFIDENCE_MAX,
+    INSTINCT_CONFIDENCE_MIN,
+    ActionableInsight,
+)
 
 
 class InsightStore:
@@ -26,6 +30,27 @@ class InsightStore:
         conn.execute("PRAGMA journal_mode=WAL")
         return conn
 
+    # Instinct columns added after the original 12-column schema. An
+    # operator's existing DB has the old shape, so these are ALTER-added
+    # with defaults rather than baked into CREATE TABLE — a fresh install
+    # gets them from CREATE, an upgrade gets them from _migrate.
+    #
+    # Each entry carries the FULL, literal ALTER statement — never an
+    # f-string built from parts. SQLite cannot parameterise a DDL
+    # identifier, so the only safe construction is a constant statement,
+    # and a constant statement is also the only one a scanner can trust:
+    # there is no interpolation site to become an injection the day these
+    # names turn dynamic.
+    _INSTINCT_COLUMNS = (
+        ("confidence",
+         "ALTER TABLE insights ADD COLUMN confidence REAL NOT NULL DEFAULT 0.5"),
+        ("scope",
+         "ALTER TABLE insights ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'"),
+        ("evidence_count",
+         "ALTER TABLE insights ADD COLUMN evidence_count "
+         "INTEGER NOT NULL DEFAULT 1"),
+    )
+
     def _init_db(self) -> None:
         with self._conn() as conn:
             conn.execute("""
@@ -41,9 +66,13 @@ class InsightStore:
                     recommendation TEXT NOT NULL,
                     context TEXT NOT NULL,
                     status TEXT NOT NULL DEFAULT 'pending',
-                    presented_at TEXT
+                    presented_at TEXT,
+                    confidence REAL NOT NULL DEFAULT 0.5,
+                    scope TEXT NOT NULL DEFAULT 'project',
+                    evidence_count INTEGER NOT NULL DEFAULT 1
                 )
             """)
+            self._migrate(conn)
             conn.execute(
                 "CREATE INDEX IF NOT EXISTS idx_insights_project ON insights (project)"
             )
@@ -51,6 +80,16 @@ class InsightStore:
                 "CREATE INDEX IF NOT EXISTS idx_insights_status ON insights (status)"
             )
 
+    def _migrate(self, conn: sqlite3.Connection) -> None:
+        """Add instinct columns to a pre-existing table. Idempotent."""
+        existing = {
+            row["name"]
+            for row in conn.execute("PRAGMA table_info(insights)").fetchall()
+        }
+        for name, alter_stmt in self._INSTINCT_COLUMNS:
+            if name not in existing:
+                conn.execute(alter_stmt)
+
     def _row_to_insight(self, row: sqlite3.Row) -> ActionableInsight:
         data = dict(row)
         # Map trigger_source back to trigger (SQL keyword workaround)
@@ -69,8 +108,8 @@ class InsightStore:
                 INSERT OR REPLACE INTO insights
                     (id, project, trigger_source, date_generated, category,
                      severity, title, description, recommendation, context,
-                     status, presented_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                     status, presented_at, confidence, scope, evidence_count)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 """,
                 (
                     insight.id,
@@ -85,6 +124,9 @@ class InsightStore:
                     insight.context,
                     insight.status,
                     insight.presented_at.isoformat() if insight.presented_at else None,
+                    insight.confidence,
+                    insight.scope,
+                    insight.evidence_count,
                 ),
             )
 
@@ -130,11 +172,12 @@ class InsightStore:
         """Mark insights as presented and record the timestamp."""
         if not ids:
             return
-        now = datetime.now(timezone.utc).isoformat()
+        now = datetime.now(UTC).isoformat()
         placeholders = ",".join("?" * len(ids))
         with self._conn() as conn:
             conn.execute(
-                f"UPDATE insights SET status = 'presented', presented_at = ? WHERE id IN ({placeholders})",
+                "UPDATE insights SET status = 'presented', presented_at = ? "
+                f"WHERE id IN ({placeholders})",
                 [now, *ids],
             )
 
@@ -151,5 +194,69 @@ class InsightStore:
             ).fetchall()
         return {r["category"]: r["cnt"] for r in rows}
 
+    def reinforce(self, insight_id: str, step: float = 0.1) -> None:
+        """Corroboration: raise confidence (clamped) and count evidence.
+
+        The clamp lives in ``ActionableInsight``; the SQL bounds mirror it
+        so a direct UPDATE cannot push a value past the band either.
+        """
+        with self._conn() as conn:
+            conn.execute(
+                """
+                UPDATE insights
+                SET confidence = MIN(?, confidence + ?),
+                    evidence_count = evidence_count + 1
+                WHERE id = ?
+                """,
+                (INSTINCT_CONFIDENCE_MAX, step, insight_id),
+            )
+
+    def weaken(self, insight_id: str, step: float = 0.2) -> None:
+        """Contradiction: lower confidence (clamped to the band floor).
+
+        A correction cuts harder than a corroboration lifts — the default
+        step is larger — because one contradiction outweighs several
+        passive confirmations.
+        """
+        with self._conn() as conn:
+            conn.execute(
+                "UPDATE insights SET confidence = MAX(?, confidence - ?) WHERE id = ?",
+                (INSTINCT_CONFIDENCE_MIN, step, insight_id),
+            )
+
+    def promotable(
+        self, min_projects: int = 2, min_confidence: float = 0.8
+    ) -> list[str]:
+        """Titles seen as project-scoped across >= min_projects distinct
+        projects with mean confidence >= min_confidence.
+
+        The signal B7 (``/arka promote``) consumes: a pattern that has
+        proven itself in more than one project has earned global scope.
+        Grouped by title because that is the instinct's stable identity
+        across projects (the id is per-occurrence).
+        """
+        with self._conn() as conn:
+            rows = conn.execute(
+                """
+                SELECT title FROM insights
+                WHERE scope = 'project'
+                GROUP BY title
+                HAVING COUNT(DISTINCT project) >= ?
+                   AND AVG(confidence) >= ?
+                """,
+                (min_projects, min_confidence),
+            ).fetchall()
+        return [r["title"] for r in rows]
+
+    def promote_to_global(self, title: str) -> int:
+        """Flip every project-scoped insight with this title to global.
+        Returns the number of rows promoted."""
+        with self._conn() as conn:
+            cur = conn.execute(
+                "UPDATE insights SET scope = 'global' WHERE title = ? AND scope = 'project'",
+                (title,),
+            )
+            return cur.rowcount
+
     def close(self) -> None:
         """No-op — connections are opened per-operation."""