arkaos 3.75.2 → 3.77.0

package/VERSION

@@ -1 +1 @@
-3.75.2
+3.77.0

package/arka/skills/flow/SKILL.md

@@ -81,6 +81,20 @@ spec why divergence is justified. Manual audit:
 Dispatch specialists via the `Agent` tool. The squad lead from Phase 3
 names them. Specialists run in parallel when work is independent.
 
+**Design-system check on UI work (PR6 v3.77.0, SHOULD `design-system-locked`).**
+Before dispatching frontend/landing specialists, run the per-project
+linter to surface UI/UX drift:
+
+```
+python -m core.governance.design_system_lint_cli <project_path>
+```
+
+If the project has a `design-system.yaml`, violations come back with
+file:line + the suggestion text declared in the YAML. The frontend
+specialist should fix existing violations OR document why the new work
+diverges. Projects without a `design-system.yaml` skip the check.
+Template: `docs/examples/design-system-example.yaml`.
+
 **Experience injection (PR3 v3.74.0).** When a specialist is dispatched,
 Synapse layer `L2.6 AgentExperiences`
 (`core/synapse/agent_experiences_layer.py`) detects the
@@ -194,6 +208,18 @@ For each item, in order:
 Do not skip items. Do not batch QA or Security across multiple
 items — each item runs the full gate chain.
 
+**DNA fidelity check at turn end (PR5 v3.76.0, SHOULD `dna-fidelity-warn`).**
+The Stop hook (`config/hooks/stop.sh`) invokes
+`core.governance.dna_fidelity.check_fidelity(agent_id, output)` for the
+current persona (from `[arka:routing]` or `[arka:dispatch]`). Violations
+of `avoid_patterns` or missing `opening_phrases` from the agent's YAML
+`signature_markers` block are recorded to
+`~/.arkaos/telemetry/dna-fidelity.jsonl` — soft-warn only in v3.76.0.
+Operator audit: `python -m core.governance.dna_fidelity_cli summary`.
+Each Agent dispatch also logs to
+`~/.arkaos/telemetry/agent-activations.jsonl`; surface dormant agents
+via `python -m core.governance.agent_activation_cli dead`.
+
 ### Phase 13 — Detailed summary
 When the TODO list is exhausted, emit a final summary: what was done,
 where it lives, how to verify, what is open for next time.

package/config/constitution.yaml

@@ -217,6 +217,16 @@ 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 PR6 Squad Intelligence Upgrade (2026-05-28) ───────
+      - id: design-system-locked
+        rule: "Each project SHOULD declare a `design-system.yaml` at its root listing tokens (colors, spacing, fonts), allowed_components, file_globs to scan, and forbidden_patterns with suggestions. The per-project linter (core.governance.design_system_lint) detects UI/UX drift — hex literals outside the palette, inline style attributes, raw HTML where a Nuxt UI component exists, etc. Adoption is opt-in per project (no YAML at project root → no violations). v3.77.0 is advisory-only; pre-commit hook integration lands in v3.77.x once the rule sets stabilise across the operator's projects."
+        enforcement: "Run via `python -m core.governance.design_system_lint_cli <project_path>` (text or JSON output, optional --exit-on-violations). Example template at `docs/examples/design-system-example.yaml`."
+
+      # ─── Rule added in PR5 Squad Intelligence Upgrade (2026-05-28) ───────
+      - id: dna-fidelity-warn
+        rule: "Agent outputs are compared against the `signature_markers` block in each agent's YAML at the end of every turn. Forbidden patterns (avoid_patterns) and missing opening phrases (opening_phrases) generate FidelityViolation records in ~/.arkaos/telemetry/dna-fidelity.jsonl. v3.76.0 is soft-warn — violations are recorded for telemetry and operator review, not blocked. Hard-block mode lands later once the marker set is calibrated against real production usage."
+        enforcement: "Stop hook (config/hooks/stop.sh) calls core.governance.dna_fidelity.check_fidelity at turn end. Telemetry inspection: python -m core.governance.dna_fidelity_cli list|summary. Agents in scope for v3.76.0: tech-lead-paulo, cqo-marta, copy-director-eduardo, tech-director-francisca. Remaining 61 agent YAMLs get signature_markers in v3.76.x curation work."
+
       # ─── 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."

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

@@ -165,6 +165,33 @@ PY
       fi
     fi
   fi
+
+  # ─── Activation tracking (PR5 v3.76.0) ─────────────────────────────
+  # Record every Task/Agent dispatch regardless of subagent_type (CQO or
+  # any other). Runs AFTER the cqo branch so verdicts don't block it.
+  # Never blocks — _ACT_ROOT reuses the same resolution as _AE_ROOT.
+  if [ -n "$SUBAGENT_TYPE" ]; then
+    _ACT_ROOT="${ARKAOS_ROOT:-}"
+    if [ -z "$_ACT_ROOT" ] && [ -f "$HOME/.arkaos/.repo-path" ]; then
+      _ACT_ROOT=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null)
+    fi
+    [ -z "$_ACT_ROOT" ] && _ACT_ROOT="$HOME/.arkaos"
+    SUBAGENT_TYPE="$SUBAGENT_TYPE" \
+    SESSION_ID="$SESSION_ID_PTU" \
+    ARKAOS_ROOT="$_ACT_ROOT" \
+    python3 - <<'PY' 2>/dev/null || true
+import os, sys
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.governance.activation_tracker import record_activation
+    record_activation(
+        subagent_type=os.environ.get("SUBAGENT_TYPE", ""),
+        session_id=os.environ.get("SESSION_ID", ""),
+    )
+except Exception:
+    pass
+PY
+  fi
 fi
 
 # Only process if there was an error

package/config/hooks/stop.sh

@@ -20,6 +20,7 @@ TRANSCRIPT_PATH=""
 STOP_HOOK_ACTIVE=""
 CWD=""
 EFFORT_LEVEL=""
+ASSISTANT_MSG_STOP=""
 if command -v jq &>/dev/null; then
   SESSION_ID=$(echo "$input" | jq -r '.session_id // ""' 2>/dev/null)
   TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcript_path // ""' 2>/dev/null)
@@ -29,6 +30,8 @@ if command -v jq &>/dev/null; then
   # $CLAUDE_EFFORT env var. Soft-block checks (kb-cite, meta-tag) only
   # run at high|xhigh; hard enforcement runs regardless.
   EFFORT_LEVEL=$(echo "$input" | jq -r '.effort.level // ""' 2>/dev/null)
+  # PR5 v3.76.0 — DNA fidelity check needs the closing assistant message.
+  ASSISTANT_MSG_STOP=$(echo "$input" | jq -r '.assistant_message // ""' 2>/dev/null)
 fi
 # Fallback to env var if stdin didn't carry it
 [ -z "$EFFORT_LEVEL" ] && EFFORT_LEVEL="${CLAUDE_EFFORT:-}"
@@ -39,6 +42,60 @@ fi
 # (whether the next turn sees a [arka:suggest] line). Record the level
 # on the telemetry row so we can later analyze suppression rates.
 
+# ─── DNA Fidelity Check (PR5 v3.76.0) ───────────────────────────────────
+# Fires for every session (no WF_MARKER dependency — fidelity is always
+# worth measuring). Extracts the dispatched persona from the last routing/
+# dispatch marker in the closing message, then calls check_fidelity() +
+# record_fidelity(). Soft-warn only, never blocks. Zero violations are
+# recorded too — absence of violations is signal.
+if [ -n "$ASSISTANT_MSG_STOP" ] && [ -n "$SESSION_ID" ] && command -v python3 &>/dev/null; then
+  _FID_ROOT="${ARKAOS_ROOT:-}"
+  if [ -z "$_FID_ROOT" ] && [ -f "$HOME/.arkaos/.repo-path" ]; then
+    _FID_ROOT=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null)
+  fi
+  [ -z "$_FID_ROOT" ] && _FID_ROOT="$HOME/.arkaos"
+
+  # Extract persona: dispatch marker takes precedence over routing.
+  # Latest match wins (tail -1). Both patterns: [arka:dispatch] X -> Y
+  # and [arka:routing] X -> Y. Persona is the right-hand side, lowercased.
+  _FIDELITY_PERSONA=""
+  _DISPATCH_HIT=$(printf '%s' "$ASSISTANT_MSG_STOP" \
+    | grep -ioE '\[arka:dispatch\][[:space:]]*[A-Za-z0-9_-]+[[:space:]]*->[[:space:]]*[A-Za-z0-9_-]+' \
+    | tail -1)
+  if [ -n "$_DISPATCH_HIT" ]; then
+    _FIDELITY_PERSONA=$(printf '%s' "$_DISPATCH_HIT" \
+      | sed -E 's/.*->[[:space:]]*//' | tr '[:upper:]' '[:lower:]')
+  else
+    _ROUTING_HIT=$(printf '%s' "$ASSISTANT_MSG_STOP" \
+      | grep -ioE '\[arka:routing\][[:space:]]*[A-Za-z0-9_-]+[[:space:]]*->[[:space:]]*[A-Za-z0-9_-]+' \
+      | tail -1)
+    if [ -n "$_ROUTING_HIT" ]; then
+      _FIDELITY_PERSONA=$(printf '%s' "$_ROUTING_HIT" \
+        | sed -E 's/.*->[[:space:]]*//' | tr '[:upper:]' '[:lower:]')
+    fi
+  fi
+
+  if [ -n "$_FIDELITY_PERSONA" ]; then
+    FIDELITY_PERSONA="$_FIDELITY_PERSONA" \
+    FIDELITY_SESSION_ID="$SESSION_ID" \
+    FIDELITY_MSG="$ASSISTANT_MSG_STOP" \
+    ARKAOS_ROOT="$_FID_ROOT" \
+    python3 - <<'PY' 2>/dev/null || true
+import os, sys
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.governance.dna_fidelity import check_fidelity, record_fidelity
+    agent_id = os.environ.get("FIDELITY_PERSONA", "")
+    session_id = os.environ.get("FIDELITY_SESSION_ID", "")
+    output = os.environ.get("FIDELITY_MSG", "")
+    violations = check_fidelity(agent_id, output)
+    record_fidelity(agent_id, session_id, violations)
+except Exception:
+    pass
+PY
+  fi
+fi
+
 # Prevent infinite loops when Stop hook was triggered by its own decision.
 if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
   exit 0

package/core/governance/activation_tracker.py

@@ -0,0 +1,178 @@
+"""Activation Tracker — PR5 Squad Intelligence Upgrade v3.76.0.
+
+Counts how often each agent (`subagent_type`) is dispatched via the Agent
+tool. Surfaces top callers and dead agents (no activation in N days).
+
+Wired into the PostToolUse hook in a later task. For now: persistence +
+query layer. Mirrors the JSONL + path-safe pattern of agent_experiences.py.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+
+try:
+    import fcntl
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False
+
+
+# ─── Module-level constant (monkeypatched by tests) ───────────────────────────
+
+TELEMETRY_PATH: Path = Path.home() / ".arkaos" / "telemetry" / "agent-activations.jsonl"
+
+
+# ─── Dataclass ────────────────────────────────────────────────────────────────
+
+@dataclass
+class Activation:
+    ts: str
+    subagent_type: str
+    session_id: str
+
+
+# ─── Internal helpers ─────────────────────────────────────────────────────────
+
+@contextmanager
+def _locked_append(path: Path):
+    """Append to path under POSIX flock; Windows falls back to O_APPEND atomicity."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = path.open("a", 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 _safe_id(value: str) -> str | None:
+    """Delegate to safe_session_id for CWE-22 path-traversal guard."""
+    return _safe_session_id_module.safe_session_id(value)
+
+
+def _parse_ts(iso: str) -> datetime | None:
+    """Parse an ISO timestamp string; return None on any failure."""
+    try:
+        return datetime.fromisoformat(iso)
+    except (TypeError, ValueError):
+        return None
+
+
+def _load_all() -> list[dict]:
+    """Single-pass read of TELEMETRY_PATH; skip malformed lines silently."""
+    entries: list[dict] = []
+    try:
+        with TELEMETRY_PATH.open(encoding="utf-8") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        return []
+    return entries
+
+
+def _filter_by_since(entries: list[dict], since: datetime | None) -> list[dict]:
+    """Remove entries whose ts is strictly before `since`. Pass-through when since is None."""
+    if since is None:
+        return entries
+    result: list[dict] = []
+    for e in entries:
+        ts = _parse_ts(e.get("ts", ""))
+        if ts is not None and ts >= since:
+            result.append(e)
+    return result
+
+
+def _most_recent_per_agent(entries: list[dict]) -> dict[str, str]:
+    """Return a map of subagent_type → latest ts string seen across all entries."""
+    latest: dict[str, str] = {}
+    for e in entries:
+        agent = e.get("subagent_type", "")
+        ts = e.get("ts", "")
+        if not agent or not ts:
+            continue
+        if agent not in latest or ts > latest[agent]:
+            latest[agent] = ts
+    return latest
+
+
+# ─── Public API ───────────────────────────────────────────────────────────────
+
+def record_activation(subagent_type: str, session_id: str) -> None:
+    """Append one JSONL activation record to TELEMETRY_PATH.
+
+    Silently drops when subagent_type is empty, fails the safe-id check,
+    or when filesystem I/O fails.
+    """
+    if not subagent_type:
+        return
+    if _safe_id(subagent_type) is None:
+        return
+    record = asdict(Activation(
+        ts=datetime.now(timezone.utc).isoformat(),
+        subagent_type=subagent_type,
+        session_id=session_id,
+    ))
+    try:
+        with _locked_append(TELEMETRY_PATH) as fh:
+            fh.write(json.dumps(record) + "\n")
+    except OSError:
+        return
+
+
+def query_top_callers(
+    *,
+    limit: int = 10,
+    since: datetime | None = None,
+) -> list[tuple[str, int]]:
+    """Return the most-dispatched subagent types in descending count order.
+
+    Reads TELEMETRY_PATH, skips malformed lines silently. Optional `since`
+    filters to activations at or after that datetime. Capped at `limit`.
+    Empty store returns [].
+    """
+    entries = _load_all()
+    entries = _filter_by_since(entries, since)
+    counter: Counter[str] = Counter()
+    for e in entries:
+        agent = e.get("subagent_type", "")
+        if agent:
+            counter[agent] += 1
+    return counter.most_common(limit)
+
+
+def query_dead_agents(*, since_days: int = 30) -> list[tuple[str, str]]:
+    """Return agents whose most-recent activation is older than `since_days`.
+
+    Returns [(subagent_type, last_seen_ts), ...] sorted ascending by
+    last_seen_ts (most-dormant first). Agents activated within the window
+    are excluded even if they have older activations too.
+    """
+    cutoff = datetime.now(timezone.utc) - timedelta(days=since_days)
+    entries = _load_all()
+    recent_map = _most_recent_per_agent(entries)
+    dead: list[tuple[str, str]] = []
+    for agent, last_ts in recent_map.items():
+        ts = _parse_ts(last_ts)
+        if ts is not None and ts < cutoff:
+            dead.append((agent, last_ts))
+    dead.sort(key=lambda pair: pair[1])
+    return dead

package/core/governance/agent_activation_cli.py

@@ -0,0 +1,107 @@
+"""CLI viewer for agent activation telemetry.
+
+Usage:
+    python -m core.governance.agent_activation_cli top [--since DAYS] [--limit N]
+    python -m core.governance.agent_activation_cli dead [--since-days N]
+
+Examples:
+    python -m core.governance.agent_activation_cli top --limit 10
+    python -m core.governance.agent_activation_cli dead --since-days 30
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, timedelta, timezone
+
+from core.governance.activation_tracker import query_dead_agents, query_top_callers
+
+
+def _since_dt(days: int | None) -> datetime | None:
+    if days is None:
+        return None
+    return datetime.now(timezone.utc) - timedelta(days=days)
+
+
+def _print_top(rows: list[tuple[str, int]]) -> int:
+    """Print rank | subagent_type | call_count table."""
+    if not rows:
+        print("No activation records found.")
+        return 0
+    print(f"{'rank':>4}  {'subagent_type':<36} {'calls':>6}")
+    print("-" * 50)
+    for rank, (agent, count) in enumerate(rows, start=1):
+        print(f"{rank:>4}  {agent:<36} {count:>6}")
+    return 0
+
+
+def _parse_ts_for_display(iso: str) -> tuple[str, int]:
+    """Return (formatted_ts, days_since) from an ISO string."""
+    try:
+        ts = datetime.fromisoformat(iso)
+        now = datetime.now(timezone.utc)
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=timezone.utc)
+        days_since = (now - ts).days
+        return ts.strftime("%Y-%m-%d %H:%M UTC"), days_since
+    except (TypeError, ValueError):
+        return iso, -1
+
+
+def _print_dead(rows: list[tuple[str, str]]) -> int:
+    """Print subagent_type | last_seen | days_since table."""
+    if not rows:
+        print("No dormant agents found.")
+        return 0
+    print(f"{'subagent_type':<36} {'last_seen':<22} {'days_since':>10}")
+    print("-" * 72)
+    for agent, last_ts in rows:
+        last_seen, days_since = _parse_ts_for_display(last_ts)
+        print(f"{agent:<36} {last_seen:<22} {days_since:>10}")
+    return 0
+
+
+def _do_top(args: argparse.Namespace) -> int:
+    since = _since_dt(args.since)
+    rows = query_top_callers(limit=args.limit, since=since)
+    return _print_top(rows)
+
+
+def _do_dead(args: argparse.Namespace) -> int:
+    rows = query_dead_agents(since_days=args.since_days)
+    return _print_dead(rows)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.governance.agent_activation_cli",
+        description="Inspect agent activation telemetry.",
+    )
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+
+    top_p = subparsers.add_parser("top", help="Show most-dispatched agents by call count.")
+    top_p.add_argument("--since", type=int, default=None, help="Limit to last N days")
+    top_p.add_argument("--limit", type=int, default=10, help="Max records (default 10)")
+
+    dead_p = subparsers.add_parser("dead", help="Show agents with no activation in N days.")
+    dead_p.add_argument(
+        "--since-days", type=int, default=30, dest="since_days",
+        help="Dormancy threshold in days (default 30)",
+    )
+    return parser
+
+
+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 == "top":
+        return _do_top(args)
+    if args.cmd == "dead":
+        return _do_dead(args)
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/core/governance/design_system_lint.py

@@ -0,0 +1,197 @@
+"""Design System Linter — PR6 Squad Intelligence Upgrade v3.77.0.
+
+Scans a project for forbidden patterns declared in its design-system.yaml.
+Opt-in per project: no YAML at root means no violations. Advisory-only in
+v3.77.0; pre-commit hook integration lands in v3.77.x.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field  # noqa: F401 (asdict kept for callers)
+from pathlib import Path
+from typing import Iterator
+
+import yaml
+
+
+# ─── Dataclasses ──────────────────────────────────────────────────────────────
+
+@dataclass
+class DesignSystem:
+    """Loaded design-system.yaml for a project."""
+
+    version: int = 1
+    project: str = ""
+    tokens: dict = field(default_factory=dict)
+    allowed_components: list[str] = field(default_factory=list)
+    file_globs: list[str] = field(default_factory=list)
+    forbidden_patterns: list[dict] = field(default_factory=list)
+
+
+@dataclass
+class DesignViolation:
+    file: str         # relative to project_path, forward slashes
+    line: int         # 1-indexed
+    pattern: str      # the regex string from forbidden_patterns
+    suggestion: str   # suggestion text from forbidden_patterns
+    matched_text: str  # the actual matched substring (cap 200 chars)
+
+
+# ─── Internal helpers ─────────────────────────────────────────────────────────
+
+def _default_file_globs() -> list[str]:
+    return ["**/*.vue", "**/*.tsx", "**/*.jsx"]
+
+
+def _escape_glob_literal(s: str) -> str:
+    """Escape a literal glob segment (no ** inside)."""
+    return re.escape(s).replace(r"\*", "[^/]*").replace(r"\?", "[^/]")
+
+
+def _glob_to_regex(glob_pattern: str) -> re.Pattern[str]:
+    """Translate a glob pattern (with ** support) to a compiled regex.
+
+    Gitignore convention: ``**/`` = zero-or-more ``dir/`` prefixes (including
+    zero), so ``**/*.vue`` matches both ``App.vue`` and ``src/App.vue``.
+    Bare ``*`` = any non-slash run; ``?`` = one non-slash char.
+    """
+    # Split on ** tokens, keeping them as delimiters.
+    tokens = re.split(r"(\*\*)", glob_pattern)
+    result = ""
+    for i, tok in enumerate(tokens):
+        if tok != "**":
+            result += _escape_glob_literal(tok)
+            continue
+        nxt = tokens[i + 1] if i + 1 < len(tokens) else ""
+        if nxt.startswith("/"):
+            # **/ → consume the slash, emit zero-or-more dir/ groups.
+            tokens[i + 1] = nxt[1:]
+            result += "(?:[^/]+/)*"
+        else:
+            # trailing ** or ** not followed by / → match any remaining path.
+            result += ".*"
+    return re.compile(f"^{result}$")
+
+
+def _glob_match(pattern: str, rel_path: str) -> bool:
+    """Return True when rel_path (forward slashes) matches the glob pattern."""
+    try:
+        return bool(_glob_to_regex(pattern).match(rel_path))
+    except re.error:
+        return False
+
+
+def _iter_matching_files(
+    project_path: Path, file_globs: list[str]
+) -> Iterator[Path]:
+    """Yield all files under project_path matching any glob in file_globs."""
+    seen: set[Path] = set()
+    for glob in file_globs:
+        for path in project_path.rglob("*"):
+            if not path.is_file():
+                continue
+            rel = path.relative_to(project_path).as_posix()
+            if _glob_match(glob, rel) and path not in seen:
+                seen.add(path)
+                yield path
+
+
+def _is_excluded(rel_path: str, exclude_paths: list[str]) -> bool:
+    """Return True if rel_path matches any exclude_paths glob or is design-system.yaml."""
+    if rel_path == "design-system.yaml":
+        return True
+    return any(_glob_match(exc, rel_path) for exc in exclude_paths)
+
+
+def _scan_file_for_pattern(
+    file_path: Path,
+    project_path: Path,
+    compiled_re: re.Pattern[str],
+    pattern: str,
+    suggestion: str,
+) -> Iterator[DesignViolation]:
+    """Read one file and yield a DesignViolation for every regex match."""
+    rel = file_path.relative_to(project_path).as_posix()
+    try:
+        text = file_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        for match in compiled_re.finditer(line):
+            yield DesignViolation(
+                file=rel,
+                line=lineno,
+                pattern=pattern,
+                suggestion=suggestion,
+                matched_text=match.group(0)[:200],
+            )
+
+
+# ─── Public API ───────────────────────────────────────────────────────────────
+
+def load_design_system(project_path: Path) -> DesignSystem | None:
+    """Load design-system.yaml from project_path root.
+
+    Returns None when the file is absent or malformed.
+    """
+    yaml_path = project_path / "design-system.yaml"
+    if not yaml_path.is_file():
+        return None
+    try:
+        raw = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    return DesignSystem(
+        version=int(raw.get("version") or 1),
+        project=str(raw.get("project") or ""),
+        tokens=dict(raw.get("tokens") or {}),
+        allowed_components=list(raw.get("allowed_components") or []),
+        file_globs=list(raw.get("file_globs") or []),
+        forbidden_patterns=list(raw.get("forbidden_patterns") or []),
+    )
+
+
+def lint_project(project_path: Path) -> list[DesignViolation]:
+    """Scan project_path for design-system violations.
+
+    Returns an empty list when the project path does not exist, has no
+    design-system.yaml, or the YAML is malformed.
+    """
+    if not project_path.is_dir():
+        return []
+    ds = load_design_system(project_path)
+    if ds is None:
+        return []
+    globs = ds.file_globs if ds.file_globs else _default_file_globs()
+    violations: list[DesignViolation] = []
+    for fp_dict in ds.forbidden_patterns:
+        if not isinstance(fp_dict, dict):
+            continue
+        _collect_pattern_violations(project_path, globs, fp_dict, violations)
+    return violations
+
+
+def _collect_pattern_violations(
+    project_path: Path,
+    file_globs: list[str],
+    fp_dict: dict,
+    violations: list[DesignViolation],
+) -> None:
+    """Compile one forbidden pattern and append matching violations in-place."""
+    raw_pattern = fp_dict.get("pattern", "")
+    suggestion = fp_dict.get("suggestion", "")
+    exclude_paths: list[str] = list(fp_dict.get("exclude_paths") or [])
+    try:
+        compiled = re.compile(raw_pattern)
+    except re.error:
+        return
+    for file_path in _iter_matching_files(project_path, file_globs):
+        rel = file_path.relative_to(project_path).as_posix()
+        if _is_excluded(rel, exclude_paths):
+            continue
+        violations.extend(
+            _scan_file_for_pattern(file_path, project_path, compiled, raw_pattern, suggestion)
+        )

package/core/governance/design_system_lint_cli.py

@@ -0,0 +1,92 @@
+"""CLI for the Design System Linter (PR6 Squad Intelligence Upgrade v3.77.0).
+
+Usage:
+    python -m core.governance.design_system_lint_cli <project_path> [--format text|json] [--exit-on-violations]
+
+Examples:
+    python -m core.governance.design_system_lint_cli /path/to/project
+    python -m core.governance.design_system_lint_cli /path/to/project --format json --exit-on-violations
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+from core.governance.design_system_lint import (
+    DesignViolation,
+    lint_project,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.governance.design_system_lint_cli",
+        description="Scan a project for design-system violations.",
+    )
+    parser.add_argument("project_path", help="Path to the project root containing design-system.yaml.")
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text).",
+    )
+    parser.add_argument(
+        "--exit-on-violations",
+        action="store_true",
+        help="Exit with code 1 when violations are found.",
+    )
+    return parser
+
+
+def _print_text(violations: list[DesignViolation]) -> None:
+    """Group violations by file, sorted by file then line, and pretty-print."""
+    print(f"{len(violations)} design-system violation(s) found:")
+    by_file: dict[str, list[DesignViolation]] = defaultdict(list)
+    for v in violations:
+        by_file[v.file].append(v)
+    for file in sorted(by_file):
+        for v in sorted(by_file[file], key=lambda x: x.line):
+            truncated = v.matched_text[:60] + ("..." if len(v.matched_text) > 60 else "")
+            print(f"  {v.file}:{v.line}  {truncated}")
+            print(f"    → {v.suggestion}")
+
+
+def _print_json(violations: list[DesignViolation]) -> None:
+    """Emit one JSON line per violation followed by a summary line (jsonl)."""
+    for v in violations:
+        print(json.dumps({
+            "file": v.file,
+            "line": v.line,
+            "pattern": v.pattern,
+            "suggestion": v.suggestion,
+            "matched_text": v.matched_text,
+        }))
+    print(json.dumps({"summary": True, "count": len(violations)}))
+
+
+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:])
+    violations = lint_project(Path(args.project_path))
+
+    if not violations:
+        if args.format == "json":
+            print(json.dumps({"violations": [], "count": 0}))
+        else:
+            print("No design-system violations.")
+        return 0
+
+    if args.format == "json":
+        _print_json(violations)
+    else:
+        _print_text(violations)
+
+    return 1 if args.exit_on_violations else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/core/governance/dna_fidelity.py

@@ -0,0 +1,246 @@
+"""DNA Fidelity Checker — PR5 Squad Intelligence Upgrade v3.76.0.
+
+Compares agent output text against the `signature_markers` block declared
+in the agent's YAML. Detects forbidden patterns (avoid_patterns) and missing
+opening phrases, then records violations to telemetry.
+
+Soft-warn mode for v1. Hard-block mode lands in a later PR once telemetry
+shows the marker set is stable. Never raises — hook helpers must not break
+the execution path.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+
+from core.shared import safe_session_id as _safe_session_id_module
+
+try:
+    import fcntl
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False
+
+
+# ─── Module-level constants (monkeypatched by tests) ──────────────────────────
+
+AGENT_YAML_SEARCH_DIRS: list[Path] = [
+    Path(__file__).resolve().parent.parent.parent / "departments",
+]
+TELEMETRY_PATH: Path = Path.home() / ".arkaos" / "telemetry" / "dna-fidelity.jsonl"
+
+_OPENING_WINDOW: int = 300
+
+
+# ─── Dataclasses ──────────────────────────────────────────────────────────────
+
+@dataclass
+class SignatureMarkers:
+    opening_phrases: list[str] = field(default_factory=list)
+    typical_patterns: list[str] = field(default_factory=list)
+    closing_style: str | None = None
+    avoid_patterns: list[str] = field(default_factory=list)
+
+
+@dataclass
+class FidelityViolation:
+    kind: str    # "forbidden_pattern" | "missing_opening"
+    pattern: str
+    span: str
+
+
+# ─── Internal helpers ─────────────────────────────────────────────────────────
+
+def _register_yaml_entry(index: dict[str, Path], path: Path, data: dict) -> None:
+    """Add all lookup keys for one agent YAML into the shared index dict.
+
+    Keys registered per file:
+    - ``data["id"].lower()``                   e.g. ``tech-lead-paulo``
+    - ``data["name"].lower()``                 e.g. ``paulo``
+    - last hyphen-separated segment of id      e.g. ``paulo`` (deduped)
+    """
+    agent_id: str | None = data.get("id")
+    if agent_id and isinstance(agent_id, str):
+        key = agent_id.lower()
+        index.setdefault(key, path)
+        suffix = key.rsplit("-", 1)[-1]
+        index.setdefault(suffix, path)
+    name: str | None = data.get("name")
+    if name and isinstance(name, str):
+        index.setdefault(name.lower(), path)
+
+
+@lru_cache(maxsize=1)
+def _index_agents() -> dict[str, Path]:
+    """Walk AGENT_YAML_SEARCH_DIRS once and build a name/id → path index.
+
+    Three keys per YAML (id, name, id-suffix) allow callers to pass the
+    short persona name (``paulo``) instead of the full id (``tech-lead-paulo``).
+    """
+    index: dict[str, Path] = {}
+    for search_dir in AGENT_YAML_SEARCH_DIRS:
+        if not search_dir.is_dir():
+            continue
+        for candidate in search_dir.rglob("*.yaml"):
+            try:
+                data = yaml.safe_load(candidate.read_text(encoding="utf-8"))
+            except (OSError, yaml.YAMLError):
+                continue
+            if isinstance(data, dict):
+                _register_yaml_entry(index, candidate, data)
+    return index
+
+
+def _yaml_path_for(agent_id: str) -> Path | None:
+    """Resolve an agent persona name to its YAML path via the index.
+
+    Returns None when agent_id fails the safe-session-id check (CWE-22
+    hardening) or when no matching YAML is found.
+    """
+    if _safe_session_id_module.safe_session_id(agent_id) is None:
+        return None
+    return _index_agents().get(agent_id.lower())
+
+
+@lru_cache(maxsize=128)
+def _load_markers(agent_id: str) -> SignatureMarkers | None:
+    """Load and parse signature_markers from an agent YAML. Cached per process."""
+    path = _yaml_path_for(agent_id)
+    if path is None:
+        return None
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    block = raw.get("signature_markers")
+    if not block or not isinstance(block, dict):
+        return None
+    return SignatureMarkers(
+        opening_phrases=block.get("opening_phrases") or [],
+        typical_patterns=block.get("typical_patterns") or [],
+        closing_style=block.get("closing_style"),
+        avoid_patterns=block.get("avoid_patterns") or [],
+    )
+
+
+# Chain cache invalidation so existing callers of `_load_markers.cache_clear()`
+# also flush the agent index (both are file-system snapshots; stale index
+# would return wrong paths after AGENT_YAML_SEARCH_DIRS is monkeypatched).
+_original_load_markers_cache_clear = _load_markers.cache_clear
+
+
+def _chained_cache_clear() -> None:
+    _index_agents.cache_clear()
+    _original_load_markers_cache_clear()
+
+
+_load_markers.cache_clear = _chained_cache_clear  # type: ignore[method-assign]
+
+
+def _search_avoid_patterns(
+    output: str, patterns: list[str]
+) -> list[FidelityViolation]:
+    """Return one FidelityViolation per avoid_pattern that matches output."""
+    violations: list[FidelityViolation] = []
+    for pattern in patterns:
+        match = re.search(pattern, output, re.IGNORECASE)
+        if match:
+            violations.append(
+                FidelityViolation(
+                    kind="forbidden_pattern",
+                    pattern=pattern,
+                    span=match.group(0),
+                )
+            )
+    return violations
+
+
+def _check_opening(
+    output: str, opening_phrases: list[str]
+) -> FidelityViolation | None:
+    """Return a violation when none of the opening phrases appear near the top."""
+    if not opening_phrases:
+        return None
+    window = output[:_OPENING_WINDOW]
+    for phrase in opening_phrases:
+        if re.search(re.escape(phrase), window, re.IGNORECASE):
+            return None
+    return FidelityViolation(
+        kind="missing_opening",
+        pattern=", ".join(opening_phrases),
+        span=output[:80],
+    )
+
+
+@contextmanager
+def _locked_append(path: Path):
+    """Append to path under POSIX flock; Windows falls back to O_APPEND atomicity."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = path.open("a", 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()
+
+
+# ─── Public API ───────────────────────────────────────────────────────────────
+
+def check_fidelity(agent_id: str, output: str) -> list[FidelityViolation]:
+    """Compare output against the agent's signature_markers.
+
+    Returns a list of FidelityViolation. Empty list means clean pass or
+    no markers defined for the agent.
+    """
+    markers = _load_markers(agent_id)
+    if markers is None:
+        return []
+    violations: list[FidelityViolation] = []
+    violations.extend(_search_avoid_patterns(output, markers.avoid_patterns))
+    opening_violation = _check_opening(output, markers.opening_phrases)
+    if opening_violation is not None:
+        violations.append(opening_violation)
+    return violations
+
+
+def record_fidelity(
+    agent_id: str,
+    session_id: str,
+    violations: list[FidelityViolation],
+) -> None:
+    """Append one JSONL telemetry record for this fidelity check.
+
+    Silently drops when agent_id is unsafe or filesystem I/O fails.
+    Zero violations are still recorded — absence of violations is signal too.
+    """
+    safe_id = _safe_session_id_module.safe_session_id(agent_id)
+    if safe_id is None:
+        return
+    record = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "agent_id": agent_id,
+        "session_id": session_id,
+        "violation_count": len(violations),
+        "violations": [asdict(v) for v in violations],
+    }
+    try:
+        with _locked_append(TELEMETRY_PATH) as fh:
+            fh.write(json.dumps(record) + "\n")
+    except OSError:
+        return

package/core/governance/dna_fidelity_cli.py

@@ -0,0 +1,149 @@
+"""CLI viewer for DNA fidelity telemetry.
+
+Usage:
+    python -m core.governance.dna_fidelity_cli list [--agent AGENT_ID] [--since DAYS] [--limit N]
+    python -m core.governance.dna_fidelity_cli summary [--since DAYS]
+
+Examples:
+    python -m core.governance.dna_fidelity_cli list --limit 10
+    python -m core.governance.dna_fidelity_cli list --agent tech-lead-paulo --since 7
+    python -m core.governance.dna_fidelity_cli summary --since 30
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+_TELEMETRY_PATH: Path = Path.home() / ".arkaos" / "telemetry" / "dna-fidelity.jsonl"
+
+
+def _load_records(since_dt: datetime | None, agent: str | None) -> list[dict]:
+    """Read JSONL, filter by agent and since, skip malformed lines silently."""
+    results: list[dict] = []
+    try:
+        with _TELEMETRY_PATH.open(encoding="utf-8") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    rec = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if agent and rec.get("agent_id") != agent:
+                    continue
+                if since_dt is not None:
+                    ts = _parse_ts(rec.get("ts", ""))
+                    if ts is None or ts < since_dt:
+                        continue
+                results.append(rec)
+    except OSError:
+        pass
+    results.sort(key=lambda r: r.get("ts", ""), reverse=True)
+    return results
+
+
+def _parse_ts(value: str) -> datetime | None:
+    """Parse ISO timestamp; return None on failure."""
+    try:
+        return datetime.fromisoformat(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _since_dt(days: int | None) -> datetime | None:
+    if days is None:
+        return None
+    return datetime.now(timezone.utc) - timedelta(days=days)
+
+
+def _format_record(rec: dict, index: int) -> str:
+    """Format a single fidelity record for list output."""
+    ts = rec.get("ts", "?")
+    agent = rec.get("agent_id", "?")
+    vcount = rec.get("violation_count", 0)
+    label = "CLEAN" if vcount == 0 else f"VIOLATIONS({vcount})"
+    lines = [f"  [{index}] {ts}  {agent}  {label}"]
+    for v in (rec.get("violations") or [])[:3]:
+        lines.append(f"        - {v.get('kind')} | {v.get('pattern')}")
+    return "\n".join(lines)
+
+
+def _do_list(args: argparse.Namespace) -> int:
+    """List fidelity records, most recent first."""
+    since = _since_dt(args.since)
+    records = _load_records(since, args.agent)
+    records = records[: args.limit]
+    if not records:
+        print("No records found.")
+        return 0
+    scope = f"agent={args.agent}" if args.agent else "all agents"
+    print(f"DNA fidelity ({len(records)} record(s), most recent first) [{scope}]:\n")
+    for i, rec in enumerate(records, start=1):
+        print(_format_record(rec, i))
+        print()
+    return 0
+
+
+def _do_summary(args: argparse.Namespace) -> int:
+    """Aggregate by agent_id, show violation rate sorted descending."""
+    since = _since_dt(args.since)
+    records = _load_records(since, agent=None)
+    if not records:
+        print("No records found.")
+        return 0
+    totals: dict[str, int] = {}
+    violations: dict[str, int] = {}
+    for rec in records:
+        aid = rec.get("agent_id", "?")
+        totals[aid] = totals.get(aid, 0) + 1
+        if rec.get("violation_count", 0) > 0:
+            violations[aid] = violations.get(aid, 0) + 1
+    rows = sorted(
+        totals.keys(),
+        key=lambda a: violations.get(a, 0) / totals[a],
+        reverse=True,
+    )
+    print(f"{'agent':<32} {'total':>6} {'violations':>10} {'rate':>8}")
+    print("-" * 62)
+    for aid in rows:
+        total = totals[aid]
+        viol = violations.get(aid, 0)
+        rate = viol / total * 100
+        print(f"{aid:<32} {total:>6} {viol:>10} {rate:>7.1f}%")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.governance.dna_fidelity_cli",
+        description="Inspect DNA fidelity telemetry records.",
+    )
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+
+    list_p = subparsers.add_parser("list", help="List fidelity records, most recent first.")
+    list_p.add_argument("--agent", default=None, help="Filter by agent_id")
+    list_p.add_argument("--since", type=int, default=None, help="Show records from last N days")
+    list_p.add_argument("--limit", type=int, default=20, help="Max records (default 20)")
+
+    summary_p = subparsers.add_parser("summary", help="Aggregate violation rate per agent.")
+    summary_p.add_argument("--since", type=int, default=None, help="Aggregate last N days only")
+    return parser
+
+
+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 == "summary":
+        return _do_summary(args)
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/departments/dev/agents/tech-lead.yaml

@@ -71,3 +71,21 @@ communication:
   avoid:
     - "blame language"
     - "vague task assignments"
+
+# PR5 v3.76.0 — DNA fidelity markers (soft-warn). Regex case-insensitive.
+# Paulo (lead, supportive style) does not gate on opening phrases — only
+# detects sycophant/placeholder language that contradicts his DISC=I
+# servant-leader tone.
+signature_markers:
+  opening_phrases: []
+  typical_patterns:
+    - "vamos"
+    - "alinhamos"
+    - "OK"
+  closing_style: null
+  avoid_patterns:
+    - "you're absolutely right"
+    - "amazing work"
+    - "great job, everyone"
+    - "I appreciate your patience"
+    - "thanks for understanding"

package/departments/quality/agents/copy-director.yaml

@@ -72,3 +72,26 @@ communication:
     - "approving text with known issues"
     - "subjective opinions without evidence"
     - "AI cliches: leverage, utilize, robust, streamline, cutting-edge"
+
+# PR5 v3.76.0 — DNA fidelity markers (soft-warn). Regex case-insensitive.
+signature_markers:
+  opening_phrases:
+    - "Copy & Language"
+    - "Reviewed"
+  typical_patterns:
+    - "PASS"
+    - "FAIL"
+    - "pt-PT"
+    - "AI cliche"
+  closing_style: null
+  avoid_patterns:
+    - "delve into"
+    - "tapestry"
+    - "in today's fast-paced"
+    - "navigate the landscape"
+    - "underscore"
+    - "leverage"
+    - "utilize"
+    - "robust"
+    - "streamline"
+    - "cutting-edge"

package/departments/quality/agents/cqo.yaml

@@ -75,3 +75,23 @@ communication:
     - "ambiguous quality feedback"
     - "soft approvals with caveats"
     - "skipping review steps"
+
+# PR5 v3.76.0 — DNA fidelity markers (soft-warn). Regex case-insensitive.
+signature_markers:
+  opening_phrases:
+    - "Quality Gate Verdict:"
+    - "Verdict:"
+  typical_patterns:
+    - "REJECTED"
+    - "APPROVED"
+    - "Final:"
+    - "does not"
+  closing_style: "Final:"
+  avoid_patterns:
+    - "you're absolutely right"
+    - "I appreciate your"
+    - "happy to help"
+    - "great question"
+    - "let me know if"
+    - "softening"
+    - "no offense"

package/departments/quality/agents/tech-director.yaml

@@ -78,3 +78,24 @@ communication:
     - "vague feedback without specific location"
     - "approving with known technical debt"
     - "skipping test coverage check"
+
+# PR5 v3.76.0 — DNA fidelity markers (soft-warn). Regex case-insensitive.
+signature_markers:
+  opening_phrases:
+    - "Technical & UX"
+    - "Technical & UX Quality"
+  typical_patterns:
+    - "B1."
+    - "M1."
+    - "PASS"
+    - "FAIL"
+    - "30-line"
+  closing_style: null
+  avoid_patterns:
+    - "I think"
+    - "I believe"
+    - "perhaps"
+    - "kind of"
+    - "sort of"
+    - "might be a"
+    - "could be a problem"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.75.2",
+  "version": "3.77.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.75.2"
+version = "3.77.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}