arkaos 3.76.0 → 3.77.0

package/VERSION

@@ -1 +1 @@
-3.76.0
+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

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 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."

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/package.json

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