arkaos 3.74.1 → 3.75.1

package/VERSION

@@ -1 +1 @@
-3.74.1
+3.75.1

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.
@@ -163,9 +171,21 @@ For each item, in order:
    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.
+   `Experience` record (only failures are lessons).
+
+   **Pattern auto-stub convention (PR4.5 v3.75.1):** to populate the
+   Pattern Library on APPROVED outcomes, the orchestrator may include
+   `[arka:pattern-suggest <id> <name>]` in the CQO dispatch prompt
+   (e.g. `[arka:pattern-suggest force-specialist-dispatch Force
+   Specialist Dispatch]`). On APPROVED, the same PostToolUse hook
+   creates a stub `PatternCard` so the library remembers the feature
+   ID and name; the operator enriches it later via `record_pattern()`
+   or by editing `~/.arkaos/patterns/cards.jsonl`. Re-suggesting an
+   existing id is a no-op (never overwrites enriched cards).
+
+   If a specialist is missing, stop and advise the user to create one
+   via `/arka personas` + provide the knowledge.
+
    - Fail → back to the todo.
 6. Document — save the completed work to Obsidian + vector DB.
 7. Next todo.

package/config/agent-ownership.yaml

@@ -148,6 +148,15 @@ ownership:
     owners: [architect, security-eng]
     reason: "Governance code requires architecture + security review"
 
+  # PR4.5 v3.75.1 — extend coverage to knowledge + synapse (Marta PR4-QG #4)
+  - pattern: "core/knowledge/**/*.py"
+    owners: [architect, senior-dev]
+    reason: "Knowledge storage + retrieval require architecture review"
+
+  - pattern: "core/synapse/**/*.py"
+    owners: [architect, senior-dev]
+    reason: "Synapse engine + layers require architecture review"
+
   - pattern: "docs/adr/**"
     owners: [architect]
     reason: "ADRs are architect's responsibility"

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

@@ -81,23 +81,26 @@ fi
 # `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
+  if [ "$SUBAGENT_TYPE" = "cqo" ]; 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
+    _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"
+
+    # ─── REJECTED → experience auto-record ────────────────────────────
+    if echo "$TOOL_OUTPUT" | grep -qE 'Quality Gate Verdict:[[:space:]]*REJECTED'; then
+      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
+        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:
@@ -111,6 +114,55 @@ try:
 except Exception:
     pass
 PY
+      fi
+    fi
+
+    # ─── APPROVED → pattern stub auto-create (PR4.5 v3.75.1) ──────────
+    # When the dispatch prompt contains `[arka:pattern-suggest <id> <name>]`
+    # AND the verdict is APPROVED, create a stub PatternCard. The
+    # operator enriches by editing ~/.arkaos/patterns/cards.jsonl or
+    # calling record_pattern() with the full metadata. Skips when the
+    # id already exists (never overwrites enriched cards).
+    if echo "$TOOL_OUTPUT" | grep -qE 'Quality Gate Verdict:[[:space:]]*APPROVED'; then
+      PATTERN_LINE=$(printf '%s' "$TOOL_INPUT_PROMPT" \
+        | grep -oE '\[arka:pattern-suggest[[:space:]]+[A-Za-z0-9_.-]+[[:space:]]+[^][]+\]' \
+        | head -1)
+      if [ -n "$PATTERN_LINE" ]; then
+        PID=$(printf '%s' "$PATTERN_LINE" | sed -E 's/\[arka:pattern-suggest[[:space:]]+([A-Za-z0-9_.-]+).*/\1/')
+        PNAME=$(printf '%s' "$PATTERN_LINE" | sed -E 's/\[arka:pattern-suggest[[:space:]]+[A-Za-z0-9_.-]+[[:space:]]+([^][]+)\]/\1/')
+        if [ -n "$PID" ] && [ -n "$PNAME" ]; then
+          PATTERN_ID="$PID" \
+          PATTERN_NAME="$PNAME" \
+          ARKAOS_ROOT="$_AE_ROOT" \
+          python3 - <<'PY' 2>/dev/null || true
+import os, sys
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from datetime import datetime, timezone
+    from core.knowledge.pattern_cards import PatternCard, record_pattern, query_patterns
+    pid = os.environ["PATTERN_ID"]
+    existing = [c for c in query_patterns(limit=1000) if c.id == pid]
+    if not existing:
+        ts = datetime.now(timezone.utc).isoformat()
+        record_pattern(PatternCard(
+            id=pid,
+            name=os.environ["PATTERN_NAME"],
+            feature_keywords=[pid.replace("-", " "), os.environ["PATTERN_NAME"].lower()],
+            description="Stub auto-created from APPROVED CQO verdict — enrich via record_pattern() or by editing the JSONL.",
+            stack=[],
+            files=[],
+            acceptance_criteria=[],
+            edge_cases=[],
+            references=[],
+            projects_using=["arkaos"],
+            created_at=ts,
+            last_updated=ts,
+        ))
+except Exception:
+    pass
+PY
+        fi
+      fi
     fi
   fi
 fi

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

@@ -188,6 +188,7 @@ def create_default_engine(
         SessionContextLayer,
     )
     from core.synapse.agent_experiences_layer import AgentExperiencesLayer
+    from core.synapse.pattern_library_layer import PatternLibraryLayer
 
     engine = SynapseEngine()
 
@@ -215,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,137 @@
+"""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 — letter-led runs of ≥4 chars, lowercased,
+# stopword-filtered. The character class includes Latin-1 Supplement
+# (À-ÿ, U+00C0–U+00FF) so pt-PT input like "autenticação", "paginação",
+# "implementação" is captured whole instead of truncated at the
+# accented character. Latin Extended-A (U+0100+) is intentionally
+# excluded — extend the class when adding CS/PL/HU/TR corpora
+# (š, ý, ě, ą, ł, ő, ı, etc.). Vector-DB embedder lands in v3.75.x.
+_WORD_RE = re.compile(r"[A-Za-zÀ-ÿ][A-Za-zÀ-ÿ0-9_-]{3,}")
+
+_STOPWORDS: frozenset[str] = frozenset({
+    # EN
+    "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",
+    # PT
+    "para", "como", "isto", "esta", "este", "isso", "essa", "esse",
+    "depois", "antes", "pode", "deve", "muito", "pelo", "pela",
+    "desde", "ainda", "assim", "porque", "mais", "menos", "sobre",
+})
+
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.74.1",
+  "version": "3.75.1",
   "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.1"
+version = "3.75.1"
 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())