arkaos 3.74.0 → 3.75.0

package/VERSION

@@ -1 +1 @@
-3.74.0
+3.75.0

package/arka/skills/flow/SKILL.md

@@ -69,6 +69,14 @@ Query the knowledge base:
 Cite the sources found. If the KB has nothing and the ask is non-trivial,
 state the gap explicitly and propose filling it.
 
+**Pattern Library check (SHOULD `pattern-library-first`, PR4 v3.75.0).**
+Synapse layer L7.5 (`core/synapse/pattern_library_layer.py`) auto-injects
+the top matching `PatternCard`s from `~/.arkaos/patterns/cards.jsonl`
+whenever the user prompt contains substantive keywords. Read the cards
+*before* designing — reuse the prior implementation, or document in the
+spec why divergence is justified. Manual audit:
+`python -m core.knowledge.pattern_cards_cli list` or `search <keyword>`.
+
 ### Phase 6 — Call team
 Dispatch specialists via the `Agent` tool. The squad lead from Phase 3
 names them. Specialists run in parallel when work is independent.
@@ -150,12 +158,20 @@ For each item, in order:
    injection, missing auth, data exposure.
    - Fail → back to the todo.
 5. **Quality Gate** — Marta (CQO) orchestrates the right specialists
-   for the area. After Marta returns the verdict, the orchestrator MUST
-   call `core.governance.cqo_experience_recorder.record_from_verdict(...)`
-   when verdict is REJECTED (constitution rule `agent-experience-persistence`,
-   MUST level — PR3 v3.74.0). The recorder parses the blockers and writes
-   one Experience to the failing agent's log so the lesson is visible on
-   the next dispatch via the L2.6 Synapse layer. If a specialist is
+   for the area.
+
+   **CQO dispatch convention (PR3.5 v3.74.1):** when invoking the `cqo`
+   subagent, the orchestrator MUST include the marker
+   `[arka:reviewing <agent_id>]` in the dispatch prompt, naming the
+   agent whose work is under review (e.g.
+   `[arka:reviewing tech-lead-paulo]`). On a REJECTED verdict, the
+   PostToolUse hook `config/hooks/post-tool-use.sh` reads the marker
+   plus the verdict text and auto-appends an `Experience` to that
+   agent's log — closing the QG learning loop without manual
+   bookkeeping. The L2.6 Synapse layer
+   (`core/synapse/agent_experiences_layer.py`) injects the lessons
+   into the next dispatch automatically. APPROVED verdicts produce no
+   record (only failures are lessons). If a specialist is
    missing, stop and advise the user
    to create one via `/arka personas` + provide the knowledge.
    - Fail → back to the todo.

package/config/agent-ownership.yaml

@@ -122,6 +122,19 @@ ownership:
     owners: [devops-eng]
     reason: "Infrastructure-as-code requires devops specialist"
 
+  # PR3.5 v3.74.1 — installer + dashboard launcher coverage
+  - pattern: "installer/**/*.js"
+    owners: [devops-eng, senior-dev]
+    reason: "npx arkaos installer surface requires devops + backend review"
+
+  - pattern: "scripts/start-dashboard*"
+    owners: [devops-eng]
+    reason: "Dashboard launcher is operational devops surface"
+
+  - pattern: "scripts/dashboard-api.py"
+    owners: [devops-eng, senior-dev]
+    reason: "Dashboard API backend bridges installer ops + Python service code"
+
   # ─── Core architecture ──────────────────────────────────────────────
   - pattern: "core/workflow/**/*.py"
     owners: [architect, senior-dev]

package/config/constitution.yaml

@@ -217,6 +217,11 @@ enforcement_levels:
         rule: "Bottom-line first output. Lead with answer, then why, then how. Confidence tags on assessments."
         enforcement: "See config/standards/communication.md for full standard"
 
+      # ─── Rule added in PR4 Squad Intelligence Upgrade (2026-05-28) ───────
+      - id: pattern-library-first
+        rule: "Before designing any new feature, consult the Pattern Library (core.knowledge.pattern_cards). If a similar pattern exists, reuse it or explicitly document why divergence is justified in the spec. New patterns SHOULD be registered with record_pattern() after Quality Gate APPROVED so future feature work inherits the prior art."
+        enforcement: "Synapse layer L7.5 (core.synapse.pattern_library_layer) auto-injects top matching cards as context. Audit via python -m core.knowledge.pattern_cards_cli list. SHOULD level — promoted from advisory once telemetry shows consistent consultation."
+
 tier_hierarchy:
   description: "Agent authority levels inspired by SpaceX/Google/Anthropic org structures"
   tiers:

package/config/hooks/post-tool-use.sh

@@ -72,6 +72,49 @@ except Exception:
   fi
 fi
 
+# ─── CQO REJECTED auto-record (PR3.5 v3.74.1) ────────────────────────
+# When a Task/Agent dispatch to subagent_type=cqo returns
+# `Quality Gate Verdict: REJECTED`, append an Experience to the
+# failing agent's log. The agent under review is identified by the
+# `[arka:reviewing <agent_id>]` marker that the orchestrator MUST
+# include in the CQO dispatch prompt (constitution rule
+# `agent-experience-persistence`). Never blocks the hook.
+if [ "$TOOL_NAME" = "Task" ] || [ "$TOOL_NAME" = "Agent" ]; then
+  SUBAGENT_TYPE=$(echo "$input" | jq -r '.tool_input.subagent_type // ""' 2>/dev/null)
+  if [ "$SUBAGENT_TYPE" = "cqo" ] && echo "$TOOL_OUTPUT" | grep -qE 'Quality Gate Verdict:[[:space:]]*REJECTED'; then
+    TOOL_INPUT_PROMPT=$(echo "$input" | jq -r '.tool_input.prompt // ""' 2>/dev/null)
+    REVIEWING_TARGET=$(printf '%s' "$TOOL_INPUT_PROMPT" \
+      | grep -oE '\[arka:reviewing[[:space:]]+[A-Za-z0-9_.-]+\]' \
+      | head -1 \
+      | sed -E 's/.*\[arka:reviewing[[:space:]]+([A-Za-z0-9_.-]+)\].*/\1/')
+    if [ -n "$REVIEWING_TARGET" ]; then
+      _AE_ROOT="${ARKAOS_ROOT:-}"
+      if [ -z "$_AE_ROOT" ] && [ -f "$HOME/.arkaos/.repo-path" ]; then
+        _AE_ROOT=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null)
+      fi
+      [ -z "$_AE_ROOT" ] && _AE_ROOT="$HOME/.arkaos"
+      VERDICT_TEXT="$TOOL_OUTPUT" \
+      AGENT_ID="$REVIEWING_TARGET" \
+      SESSION_ID="$SESSION_ID_PTU" \
+      ARKAOS_ROOT="$_AE_ROOT" \
+      python3 - <<'PY' 2>/dev/null || true
+import os, sys
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.governance.cqo_experience_recorder import record_from_verdict
+    record_from_verdict(
+        verdict_text=os.environ.get("VERDICT_TEXT", ""),
+        agent_id=os.environ.get("AGENT_ID", ""),
+        session_id=os.environ.get("SESSION_ID", ""),
+        context="auto-recorded via PostToolUse hook (cqo dispatch REJECTED)",
+    )
+except Exception:
+    pass
+PY
+    fi
+  fi
+fi
+
 # Only process if there was an error
 if [ "$EXIT_CODE" = "0" ] || [ -z "$EXIT_CODE" ]; then
   # Also check for error patterns in output even with exit code 0

package/core/knowledge/pattern_cards.py

@@ -0,0 +1,175 @@
+"""Pattern Library — append-style store of prior implementations.
+
+When a feature ships and Marta APPROVES it, the orchestrator may
+register a `PatternCard` so future feature work has a "we have
+already built this" reference: files, AC, edge cases, references.
+The Synapse L7.5 layer queries this store on every user prompt and
+injects top matching cards as context.
+
+For v1 (PR4 v3.75.0): keyword + tag matching, recency-sorted, dedup
+by id. Semantic similarity via vector embeddings lands in v3.75.x.
+
+PR4 of the Squad Intelligence Upgrade.
+"""
+
+from __future__ import annotations
+
+import json
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+
+try:
+    import fcntl  # POSIX only
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False
+
+
+PATTERNS_PATH: Path = Path.home() / ".arkaos" / "patterns" / "cards.jsonl"
+
+
+@dataclass
+class PatternCard:
+    """One reusable feature implementation pattern."""
+
+    id: str
+    name: str
+    feature_keywords: list[str]
+    description: str
+    stack: list[str]
+    files: list[str] = field(default_factory=list)
+    acceptance_criteria: list[str] = field(default_factory=list)
+    edge_cases: list[str] = field(default_factory=list)
+    references: list[str] = field(default_factory=list)
+    projects_using: list[str] = field(default_factory=list)
+    created_at: str = ""
+    last_updated: str = ""
+
+
+def pattern_to_dict(card: PatternCard) -> dict:
+    """Public serialiser for callers that persist outside this store."""
+    return asdict(card)
+
+
+def _safe_id(id_: str) -> str | None:
+    """Apply the same allowlist as session/agent IDs (CWE-22 guard)."""
+    return _safe_session_id_module.safe_session_id(id_)
+
+
+@contextmanager
+def _locked(path: Path, mode: str):
+    """Open `path` under an exclusive POSIX flock with Windows fallback."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = path.open(mode, encoding="utf-8")
+    try:
+        if _HAS_FLOCK:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+        yield fh
+    finally:
+        if _HAS_FLOCK:
+            try:
+                fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        fh.close()
+
+
+def _load_all() -> list[PatternCard]:
+    """Load all valid PatternCards. Malformed lines are skipped."""
+    if not PATTERNS_PATH.exists():
+        return []
+    cards: list[PatternCard] = []
+    try:
+        with PATTERNS_PATH.open(encoding="utf-8") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    data = json.loads(line)
+                    cards.append(PatternCard(**data))
+                except (json.JSONDecodeError, TypeError, ValueError):
+                    continue
+    except OSError:
+        return []
+    return cards
+
+
+def _stamp_card(card: PatternCard) -> None:
+    """Set created_at on first persist, last_updated on every persist."""
+    now = datetime.now(timezone.utc).isoformat()
+    if not card.created_at:
+        card.created_at = now
+    card.last_updated = now
+
+
+def _write_all(cards: list[PatternCard]) -> None:
+    """Atomically rewrite the entire JSONL. Locked for cross-process safety."""
+    try:
+        with _locked(PATTERNS_PATH, "w") as fh:
+            for c in cards:
+                fh.write(json.dumps(asdict(c)) + "\n")
+    except OSError:
+        return
+
+
+def record_pattern(card: PatternCard) -> None:
+    """Persist a PatternCard. Silently drops on unsafe/empty id.
+
+    Re-recording an existing id REPLACES the prior entry (dedup-by-id).
+    The file is rewritten in full under exclusive lock — fine for the
+    expected scale (low thousands of cards). Larger scales should move
+    to per-card files in v3.75.x.
+    """
+    if _safe_id(card.id) is None:
+        return
+    _stamp_card(card)
+    others = [c for c in _load_all() if c.id != card.id]
+    others.append(card)
+    _write_all(others)
+
+
+def _card_text(card: PatternCard) -> str:
+    """Flatten searchable text from a card."""
+    parts = [card.name, card.description] + (card.feature_keywords or [])
+    return " ".join(str(p) for p in parts).lower()
+
+
+def _matches_keywords(card: PatternCard, keywords: list[str]) -> bool:
+    if not keywords:
+        return True
+    text = _card_text(card)
+    return any(kw.lower() in text for kw in keywords)
+
+
+def _matches_tags(card: PatternCard, tags: list[str]) -> bool:
+    if not tags:
+        return True
+    stack = {t.lower() for t in (card.stack or [])}
+    return any(tag.lower() in stack for tag in tags)
+
+
+def query_patterns(
+    *,
+    keywords: list[str] | None = None,
+    tags: list[str] | None = None,
+    limit: int = 10,
+) -> list[PatternCard]:
+    """Return cards matching ALL filters, most recent first.
+
+    Empty filters return all cards. Match semantics: case-insensitive
+    substring on name/description/feature_keywords; exact tag match
+    against `stack`. Both filters must hold (intersection).
+    """
+    cards = _load_all()
+    kws = keywords or []
+    tgs = tags or []
+    matched = [
+        c for c in cards
+        if _matches_keywords(c, kws) and _matches_tags(c, tgs)
+    ]
+    matched.sort(key=lambda c: c.last_updated or c.created_at, reverse=True)
+    return matched[:limit]

package/core/knowledge/pattern_cards_cli.py

@@ -0,0 +1,103 @@
+"""CLI viewer for the Pattern Library.
+
+Usage:
+    python -m core.knowledge.pattern_cards_cli list [--tag TAG] [--limit N]
+    python -m core.knowledge.pattern_cards_cli search <keyword> [--tag TAG] [--limit N]
+    python -m core.knowledge.pattern_cards_cli show <id>
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from core.knowledge.pattern_cards import PatternCard, query_patterns
+
+
+def _format_card(card: PatternCard, index: int | None = None) -> str:
+    head = f"  [{index}] " if index is not None else "  "
+    lines = [f"{head}{card.id} — {card.name}"]
+    if card.stack:
+        lines.append(f"      stack: {', '.join(card.stack)}")
+    if card.description:
+        lines.append(f"      {card.description}")
+    if card.files:
+        lines.append(f"      files: {', '.join(card.files[:5])}")
+    if card.acceptance_criteria:
+        lines.append("      AC:")
+        for ac in card.acceptance_criteria[:3]:
+            lines.append(f"        - {ac}")
+    if card.references:
+        lines.append(f"      refs: {', '.join(card.references[:3])}")
+    return "\n".join(lines)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.knowledge.pattern_cards_cli",
+        description="Browse the ArkaOS Pattern Library.",
+    )
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+
+    list_p = subparsers.add_parser("list", help="List all patterns by recency.")
+    list_p.add_argument("--tag", default=None, help="Filter by stack tag")
+    list_p.add_argument("--limit", type=int, default=20, help="Max records")
+
+    search_p = subparsers.add_parser("search", help="Search by keyword.")
+    search_p.add_argument("keyword", help="Keyword (case-insensitive substring)")
+    search_p.add_argument("--tag", default=None, help="Filter by stack tag")
+    search_p.add_argument("--limit", type=int, default=20, help="Max records")
+
+    show_p = subparsers.add_parser("show", help="Show one card by id.")
+    show_p.add_argument("id", help="Pattern id slug")
+    return parser
+
+
+def _do_list(args) -> int:
+    tags = [args.tag] if args.tag else None
+    cards = query_patterns(tags=tags, limit=args.limit)
+    return _print_list(cards, scope="all")
+
+
+def _do_search(args) -> int:
+    tags = [args.tag] if args.tag else None
+    cards = query_patterns(keywords=[args.keyword], tags=tags, limit=args.limit)
+    return _print_list(cards, scope=f"matching '{args.keyword}'")
+
+
+def _do_show(args) -> int:
+    cards = query_patterns()
+    for c in cards:
+        if c.id == args.id:
+            print(_format_card(c))
+            return 0
+    print(f"No pattern with id '{args.id}'.")
+    return 1
+
+
+def _print_list(cards: list[PatternCard], *, scope: str) -> int:
+    if not cards:
+        print(f"No patterns {scope}.")
+        return 0
+    print(f"Patterns {scope} ({len(cards)} record(s), most recent first):\n")
+    for i, c in enumerate(cards, start=1):
+        print(_format_card(c, index=i))
+        print()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+    if args.cmd == "list":
+        return _do_list(args)
+    if args.cmd == "search":
+        return _do_search(args)
+    if args.cmd == "show":
+        return _do_show(args)
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/core/synapse/engine.py

@@ -187,6 +187,8 @@ def create_default_engine(
         ForgeContextLayer,
         SessionContextLayer,
     )
+    from core.synapse.agent_experiences_layer import AgentExperiencesLayer
+    from core.synapse.pattern_library_layer import PatternLibraryLayer
 
     engine = SynapseEngine()
 
@@ -194,6 +196,10 @@ def create_default_engine(
     engine.register_layer(l0)
     engine.register_layer(DepartmentLayer())
     engine.register_layer(AgentLayer(agents_registry=agents_registry))
+    # L2.6 (PR3.5 v3.74.1) — injects past Quality Gate experiences for the
+    # specialist named in `[arka:dispatch]`, so dispatched agents inherit
+    # prior REJECTED lessons across sessions. Closes the PR3 loop.
+    engine.register_layer(AgentExperiencesLayer())
     if vector_store is not None or kb_vault_path:
         engine.register_layer(
             KBContextLayer(
@@ -210,6 +216,11 @@ def create_default_engine(
     engine.register_layer(QualityGateLayer())
     engine.register_layer(TimeLayer())
     engine.register_layer(ForgeContextLayer())
+    # L7.5 (PR4 v3.75.0) — Pattern Library injection. Surfaces prior
+    # `PatternCard`s when the user prompt has matching keywords, so
+    # specs and dispatched specialists start from prior art rather than
+    # reinventing.
+    engine.register_layer(PatternLibraryLayer())
     engine.register_layer(SessionContextLayer())
 
     return engine

package/core/synapse/pattern_library_layer.py

@@ -0,0 +1,129 @@
+"""Synapse layer L7.5 — Pattern Library injection.
+
+When the user's prompt has substantive keywords overlapping a recorded
+`PatternCard`, this layer surfaces the top-3 matching cards as context
+so the orchestrator (and the dispatched specialists) start from the
+"we have already built this" prior art rather than reinventing.
+
+Matching is keyword-substring + tag overlap for v1. Semantic similarity
+via vector embeddings lands in v3.75.x.
+
+PR4 of the Squad Intelligence Upgrade.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+from core.knowledge.pattern_cards import PatternCard, query_patterns
+from core.synapse.layers import Layer, LayerResult, PromptContext
+
+
+# Cheap keyword extractor — alphanumeric runs longer than 3 chars,
+# lowercased, stopword-filtered. Enough for v1 matching; a vector-DB
+# embedder will replace this in v3.75.x.
+_WORD_RE = re.compile(r"[A-Za-z][A-Za-z0-9_-]{3,}")
+
+_STOPWORDS: frozenset[str] = frozenset({
+    "this", "that", "with", "from", "into", "have", "want", "need",
+    "should", "would", "could", "make", "made", "thing", "things",
+    "there", "their", "about", "what", "when", "where", "which",
+    "while", "also", "just", "like", "para", "como", "isto",
+    "esta", "este", "isso", "essa", "esse", "depois", "antes",
+})
+
+
+def _extract_keywords(text: str, max_n: int = 10) -> list[str]:
+    """Return the first `max_n` distinct meaningful words from `text`."""
+    seen: list[str] = []
+    seen_set: set[str] = set()
+    for word in _WORD_RE.findall(text or ""):
+        low = word.lower()
+        if low in _STOPWORDS or low in seen_set:
+            continue
+        seen.append(low)
+        seen_set.add(low)
+        if len(seen) >= max_n:
+            break
+    return seen
+
+
+class PatternLibraryLayer(Layer):
+    """L7.5 — surface prior implementations matching the user prompt."""
+
+    def __init__(self, limit: int = 3) -> None:
+        self._limit = limit
+
+    @property
+    def id(self) -> str:
+        return "L7.5"
+
+    @property
+    def name(self) -> str:
+        return "PatternLibrary"
+
+    @property
+    def cache_ttl(self) -> int:
+        return 60
+
+    @property
+    def priority(self) -> int:
+        # 75 — runs after L7 Time (70) and BEFORE L8 ForgeContext (80) so
+        # the prior-art context is available to Forge's plan synthesis.
+        return 75
+
+    def compute(self, ctx: PromptContext) -> LayerResult:
+        start = time.time()
+        keywords = _extract_keywords(ctx.user_input)
+        if not keywords:
+            return self._empty_result(start)
+
+        cards = query_patterns(keywords=keywords, limit=self._limit)
+        if not cards:
+            return self._empty_result(start, tag="[patterns:none]")
+
+        content = format_patterns(cards)
+        ms = int((time.time() - start) * 1000)
+        return LayerResult(
+            layer_id=self.id,
+            tag=f"[patterns:{len(cards)}]",
+            content=content,
+            tokens_est=max(1, len(content) // 4),
+            compute_ms=ms,
+            cached=False,
+        )
+
+    def _empty_result(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 format_patterns(cards: list[PatternCard]) -> str:
+    """Render a compact, model-readable summary of prior implementations."""
+    lines = [
+        "Prior implementations found in the Pattern Library "
+        "(consult before designing — reuse or document divergence):"
+    ]
+    for i, c in enumerate(cards, start=1):
+        head = f"  {i}. {c.name} ({c.id})"
+        if c.stack:
+            head += f" — stack: {', '.join(c.stack[:4])}"
+        lines.append(head)
+        if c.description:
+            lines.append(f"     {c.description}")
+        if c.files:
+            lines.append(f"     files: {', '.join(c.files[:3])}")
+        if c.acceptance_criteria:
+            lines.append(
+                f"     AC: {'; '.join(c.acceptance_criteria[:2])}"
+            )
+        if c.references:
+            lines.append(f"     refs: {', '.join(c.references[:2])}")
+    return "\n".join(lines)

package/installer/cli.js

@@ -21,6 +21,10 @@ const { values, positionals } = parseArgs({
     force: { type: "boolean", short: "f" },
     "no-system": { type: "boolean" },
     "with-ollama": { type: "boolean" },
+    // PR3.5 v3.74.1 — declared so `npx arkaos doctor --fix` lands in
+    // `values.fix` rather than as a free positional under strict:false.
+    // Eliminates the dead-branch fallback flagged by Marta in PR2's QG.
+    fix: { type: "boolean" },
   },
   allowPositionals: true,
   strict: false,
@@ -94,8 +98,7 @@ async function main() {
 
     case "doctor": {
       const { doctor } = await import("./doctor.js");
-      const fixMode = positionals.slice(1).includes("--fix") || values.fix === true;
-      await doctor({ fix: fixMode });
+      await doctor({ fix: values.fix === true });
       break;
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.74.0",
+  "version": "3.75.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "3.74.0"
+version = "3.75.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/seed_initial_patterns.py

@@ -0,0 +1,184 @@
+"""One-shot seeder for the ArkaOS Pattern Library.
+
+Populates `~/.arkaos/patterns/cards.jsonl` with the four patterns
+shipped in PR1–PR3.5 of the Squad Intelligence Upgrade so the library
+starts with real day-1 data instead of waiting for the operator to
+record patterns manually.
+
+Idempotent: re-running replaces same-id entries (the recorder dedups).
+
+Usage:
+    python -m scripts.seed_initial_patterns
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from core.knowledge.pattern_cards import PatternCard, record_pattern
+
+
+def _ts(year: int, month: int, day: int) -> str:
+    return datetime(year, month, day, tzinfo=timezone.utc).isoformat()
+
+
+_INITIAL_PATTERNS: list[PatternCard] = [
+    PatternCard(
+        id="force-specialist-dispatch",
+        name="Force Specialist Dispatch",
+        feature_keywords=[
+            "specialist", "dispatch", "ownership", "file-glob", "owner",
+            "agent", "persona", "pretooluse", "hook", "enforcement",
+        ],
+        description=(
+            "PreToolUse hook that blocks Tier-1 squad leads from writing "
+            "to specialist-owned files unless they dispatch the specialist "
+            "via the Agent tool first."
+        ),
+        stack=["python", "bash", "powershell", "hook", "constitution", "governance"],
+        files=[
+            "core/workflow/specialist_enforcer.py",
+            "config/agent-ownership.yaml",
+            "config/hooks/pre-tool-use.sh",
+            "config/hooks/pre-tool-use.ps1",
+        ],
+        acceptance_criteria=[
+            "BLOCK lead writes on specialist-owned files",
+            "Bypass via [arka:specialist-bypass <reason>] (non-empty reason)",
+            "Telemetry to ~/.arkaos/telemetry/specialist-dispatch.jsonl",
+            "Path-traversal safe via safe_session_id",
+            "Feature flag hooks.specialistEnforcement defaults off",
+        ],
+        edge_cases=[
+            "Subagent transcripts isolated from parent — negative gate only",
+            "Bypass marker scope strict: last assistant message only",
+            "C-Suite + lead_allowed cross-cutting paths always pass",
+        ],
+        references=[
+            "https://github.com/andreagroferreira/arka-os/pull/204",
+            "docs/adr/2026-05-28-specialist-dispatch-subagent-blindspot.md",
+        ],
+        projects_using=["arkaos"],
+        created_at=_ts(2026, 5, 28),
+        last_updated=_ts(2026, 5, 28),
+    ),
+    PatternCard(
+        id="dashboard-venv-doctor",
+        name="Dashboard venv-doctor",
+        feature_keywords=[
+            "venv", "dashboard", "python", "broken", "symlink", "repair",
+            "doctor", "homebrew", "rotation", "fail-fast",
+        ],
+        description=(
+            "Detects broken venv symlinks (typical after Homebrew Python "
+            "patch rotations) and auto-repairs via `python -m venv --clear`. "
+            "Dashboard launcher scripts fail-fast with actionable remediation."
+        ),
+        stack=["nodejs", "bash", "powershell", "installer"],
+        files=[
+            "installer/python-resolver.js",
+            "installer/doctor.js",
+            "scripts/start-dashboard.sh",
+            "scripts/start-dashboard.ps1",
+        ],
+        acceptance_criteria=[
+            "lstat-based broken-symlink detection (existsSync follows links)",
+            "--clear recreate + post-repair re-diagnose",
+            "Dashboard never falls back to ambient python3",
+            "npx arkaos doctor --fix auto-repairs in place",
+        ],
+        edge_cases=[
+            "Homebrew patch-version rotation (3.13.X -> 3.13.Y)",
+            "sqlite-vec optional with graceful degradation",
+        ],
+        references=[
+            "https://github.com/andreagroferreira/arka-os/pull/205",
+        ],
+        projects_using=["arkaos"],
+        created_at=_ts(2026, 5, 28),
+        last_updated=_ts(2026, 5, 28),
+    ),
+    PatternCard(
+        id="agent-experience-persistence",
+        name="Agent Experience persistence (QG learning loop)",
+        feature_keywords=[
+            "experience", "learning", "loop", "qg", "rejected", "persistence",
+            "memory", "agent", "quality-gate", "verdict",
+        ],
+        description=(
+            "REJECTED Quality Gate verdicts persist as Experience records on "
+            "the failing agent's log. Synapse layer L2.6 surfaces past "
+            "lessons when the same agent is dispatched again."
+        ),
+        stack=["python", "synapse", "governance", "constitution", "jsonl"],
+        files=[
+            "core/governance/agent_experiences.py",
+            "core/governance/cqo_experience_recorder.py",
+            "core/synapse/agent_experiences_layer.py",
+            "core/governance/agent_experiences_cli.py",
+        ],
+        acceptance_criteria=[
+            "Append-only JSONL with path-safe agent_id (CWE-22)",
+            "Verdict parser: APPROVED, REJECTED, UNKNOWN",
+            "Blockers parsed with B/M/N labels (./:/ space separators)",
+            "Multiple patterns surface in registry order (not first-match-wins)",
+        ],
+        edge_cases=[
+            "Inline mid-paragraph blockers are NOT extracted (anchored regex)",
+            "Pattern field is list[str] for multi-category failures",
+        ],
+        references=[
+            "https://github.com/andreagroferreira/arka-os/pull/206",
+        ],
+        projects_using=["arkaos"],
+        created_at=_ts(2026, 5, 28),
+        last_updated=_ts(2026, 5, 28),
+    ),
+    PatternCard(
+        id="qg-experience-loop-wiring",
+        name="QG Experience Loop Wiring",
+        feature_keywords=[
+            "posttooluse", "hook", "auto-record", "wiring", "integration",
+            "loop", "reviewing", "cqo",
+        ],
+        description=(
+            "PostToolUse hook auto-detects Agent calls with subagent_type=cqo "
+            "returning REJECTED, parses [arka:reviewing <agent_id>], invokes "
+            "record_from_verdict. Synapse L2.6 registered in engine."
+        ),
+        stack=["bash", "python", "synapse", "hook"],
+        files=[
+            "config/hooks/post-tool-use.sh",
+            "core/synapse/engine.py",
+        ],
+        acceptance_criteria=[
+            "[arka:reviewing <agent_id>] marker in CQO dispatch prompt",
+            "Auto-record on REJECTED verdict via PostToolUse hook",
+            "Path-traversal-safe by double boundary (shell + Python)",
+            "Never blocks the hook",
+        ],
+        edge_cases=[
+            "subagent_type exact 'cqo' (no sub-reviewer variants yet)",
+            "Idempotent: same output processed twice writes two records",
+        ],
+        references=[
+            "https://github.com/andreagroferreira/arka-os/pull/207",
+        ],
+        projects_using=["arkaos"],
+        created_at=_ts(2026, 5, 28),
+        last_updated=_ts(2026, 5, 28),
+    ),
+]
+
+
+def main() -> int:
+    for card in _INITIAL_PATTERNS:
+        record_pattern(card)
+    print(f"Seeded {len(_INITIAL_PATTERNS)} pattern cards.")
+    print("Inspect: python -m core.knowledge.pattern_cards_cli list")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    import sys
+    sys.exit(main())