@event4u/agent-config 5.10.1 → 6.1.0

package/src/scripts/skill_linter.py

@@ -0,0 +1,3694 @@
+#!/usr/bin/env python3
+"""
+Minimal skill/rule linter for agent-config repositories.
+
+MVP checks:
+- Detect skill vs rule
+- Required skill sections
+- Basic rule validation
+- Vague validation detection
+- Output format presence
+- Gotchas / Do NOT presence
+- Single file, --all, --changed
+- Text and JSON output
+
+Exit codes:
+0 = pass
+1 = warnings only
+2 = errors
+3 = internal error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Iterable, List, Literal, Optional
+
+# Sibling module — stdlib-only frontmatter schema validator.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from validate_frontmatter import (  # noqa: E402
+    apply_schema_defaults,
+    parse_frontmatter as parse_frontmatter_for_schema,
+    load_schema,
+    validate as validate_against_schema,
+)
+from _lib.agent_src import artefact_roots, resolve_logical  # noqa: E402
+
+Severity = Literal["error", "warning", "info"]
+ArtifactType = Literal["skill", "rule", "command", "guideline", "persona", "user-type", "unknown"]
+
+REQUIRED_PERSONA_SECTIONS_CORE = [
+    "Focus",
+    "Mindset",
+    "Unique Questions",
+    "Output Expectations",
+    "Anti-Patterns",
+]
+REQUIRED_PERSONA_SECTIONS_SPECIALIST = REQUIRED_PERSONA_SECTIONS_CORE + [
+    "Critical Rules",
+    "Workflows",
+]
+# Back-compat alias — used by tier-agnostic callers; defaults to the core spine.
+REQUIRED_PERSONA_SECTIONS = REQUIRED_PERSONA_SECTIONS_CORE
+VALID_PERSONA_TIERS = {"core", "specialist"}
+# Locked in docs/contracts/persona-schema.md § 4: core ≤ 120, specialist ≤ 100.
+PERSONA_LINE_BUDGETS = {"core": 120, "specialist": 100}
+
+# User-type spine — locked in docs/contracts/user-type-schema.md § 3.
+# Runtime end-user simulation lens (sister axis to personas — methodology vs
+# end-user). Single tier in v1 (no core/specialist split).
+REQUIRED_USERTYPE_SECTIONS = [
+    "Focus",
+    "Daily Workflow",
+    "Vocabulary",
+    "Operational Constraints",
+    "Unique Questions",
+    "Ticket Red Flags",
+    "Anti-Patterns",
+]
+USERTYPE_LINE_BUDGET = 120
+# Wing-scoped overrides — Wing-3 (GTM) and Wing-4 (Money/Strategy/Ops) carry
+# denser cognition (funnel × channel × lifecycle, or finance × org × strategy)
+# than Wing-1/2 specialists, so the line cap rises to keep the seven-section
+# spine intact without amputating workflows. Persona-schema.md § 4 wing matrix.
+VALID_PERSONA_WINGS = {1, 2, 3, 4}
+PERSONA_LINE_BUDGETS_BY_WING = {
+    ("specialist", 3): 140,
+    ("specialist", 4): 140,
+}
+
+
+REQUIRED_SKILL_SECTIONS = [
+    "When to use",
+    "Gotcha",
+    "Procedure",
+    "Output format",
+    "Do NOT",
+]
+
+# Aliases: linter accepts any of these as matching the required section
+SECTION_ALIASES = {
+    "Gotcha": {"Gotcha", "Gotchas"},
+    "Procedure": set(),  # prefix-matched separately
+    "Do NOT": {"Do NOT", "Do not", "Anti-patterns"},
+    "Output format": {"Output format", "Output"},
+}
+
+RECOMMENDED_SKILL_SECTIONS: list[str] = []
+
+RULE_BAD_SIGNS = [
+    "## Procedure",
+    "## Output format",
+    "## Gotchas",
+]
+
+# --- Frugality charter validator (see road-to-token-frugality Phase 0.4) ---
+# Layer 1 = writer-cite check (every writer skill carries the section + link).
+# Layer 2 = charter index integrity (the four canonical rules referenced by
+# the charter resolve to real H2/H3 anchors in the rule files).
+
+FRUGALITY_WRITER_SKILLS = {
+    "skill-writing", "rule-writing", "command-writing",
+    "guideline-writing", "context-authoring", "agent-docs-writing",
+    "conventional-commits-writing", "readme-writing",
+    "readme-writing-package", "adr-create",
+    "persona-writing", "roadmap-writing", "script-writing",
+}
+FRUGALITY_CHARTER_RELPATH = "contexts/communication/frugality-charter.md"
+FRUGALITY_CHARTER_INDEX_RULES = {
+    "direct-answers.md": "iron-law-3",
+    "user-interaction.md": "iron-law-1",
+    "no-cheap-questions.md": "pre-send-self-check",
+    "token-efficiency.md": "the-iron-laws",
+}
+
+VAGUE_VALIDATION_PATTERNS = [
+    r"\bcheck if it works\b",
+    r"\bverify it works\b",
+    r"\btest manually\b",
+    r"\bcheck manually\b",
+    r"\bmake sure it works\b",
+]
+
+TRIGGER_WARNING_PATTERNS = [
+    r"\bgeneral helper\b",
+    r"\blaravel skill\b",
+    r"\bgeneral coding\b",
+    r"\beverything about\b",
+]
+
+ORDERED_STEP_PATTERN = re.compile(r"^(?:\s*|\#{1,4}\s*)(\d+)\.\s+", re.MULTILINE)
+SECTION_PATTERN = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
+FRONTMATTER_PATTERN = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+DESCRIPTION_PATTERN = re.compile(r'^description:\s*"?(.*?)"?\s*$', re.MULTILINE)
+TYPE_PATTERN = re.compile(r'^type:\s*"?(always|auto|manual)"?\s*$', re.MULTILINE)
+SOURCE_PATTERN = re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE)
+STATUS_PATTERN = re.compile(r'^status:\s*"?(active|deprecated|superseded)"?\s*$', re.MULTILINE)
+REPLACED_BY_PATTERN = re.compile(r'^replaced_by:\s*"?([\w-]+)"?\s*$', re.MULTILINE)
+TIER_PATTERN = re.compile(r'^tier:\s*"?([\w-]+)"?\s*$', re.MULTILINE)
+
+# --- Senior-tier required-block patterns (skill-quality.md § Senior-Tier Required Structure) ---
+# Heading-only checks; detail-shape lives in skill-quality-mechanics.md.
+SENIOR_RELATED_SKILLS_PATTERN = re.compile(r"^##\s+Related Skills\s*$", re.MULTILINE)
+SENIOR_RELATED_WHEN_PATTERN = re.compile(r"\*\*WHEN to use this\*\*", re.IGNORECASE)
+SENIOR_RELATED_WHEN_NOT_PATTERN = re.compile(r"\*\*WHEN NOT to use this\*\*", re.IGNORECASE)
+SENIOR_PROACTIVE_PATTERN = re.compile(
+    r"^##\s+When the agent should load this\s*$", re.MULTILINE
+)
+SENIOR_OUTPUT_PATTERN = re.compile(r"^##\s+Output\s*$", re.MULTILINE)
+H1_PATTERN = re.compile(r"^# .+", re.MULTILINE)
+DOUBLE_BLANK_PATTERN = re.compile(r"\n{3,}")
+
+VALID_RULE_TYPES = {"always", "auto", "manual"}
+VALID_RULE_SOURCES = {"package", "project"}
+VALID_STATUSES = {"active", "deprecated", "superseded"}
+
+# --- Router schema (docs/contracts/rule-router.md) ---
+ROUTER_ALLOWED_TRIGGER_KEYS = {"keyword", "phrase", "intent", "file_pattern",
+                               "path_prefix", "command"}
+ROUTER_ALLOWED_PROFILES = {"minimal", "balanced", "full"}
+KERNEL_RULE_IDS: set[str] = {
+    "agent-authority", "ask-when-uncertain", "commit-policy",
+    "direct-answers", "language-and-tone", "no-cheap-questions",
+    "non-destructive-by-default", "scope-control",
+    "verify-before-complete",
+}
+
+# --- Runtime execution metadata constants ---
+VALID_EXECUTION_TYPES = {"manual", "assisted", "automated"}
+VALID_EXECUTION_HANDLERS = {"none", "shell", "php", "node", "internal"}
+VALID_EXECUTION_SAFETY_MODES = {"strict"}
+VALID_EXECUTION_FIELDS = {"type", "handler", "timeout_seconds", "safety_mode", "allowed_tools", "command"}
+
+# --- Wing-3 GTM cognition-boundary patterns (council Q7 / iter-2 OQ3) ---
+# Triggered only when a skill's context_spine declares a Wing-3 slot.
+# See docs/contracts/adr-gtm-context-spine.md and
+# agents/roadmaps/road-to-gtm-and-growth.md § G2.
+WING3_SPINE_SLOTS = {"channel-stage", "funnel-stage", "customer-segment"}
+
+CONTEXT_SPINE_INLINE_PATTERN = re.compile(
+    r'^context_spine:\s*\[(.*?)\]\s*$', re.MULTILINE
+)
+
+# agent-operability: external SaaS URLs the agent would have to auth against
+WING3_SAAS_URL_PATTERN = re.compile(
+    r"https?://[\w.-]*\.(salesforce|hubspot|marketo|pardot|mailchimp|"
+    r"intercom|amplitude|mixpanel|segment|klaviyo|sendgrid|mailgun|"
+    r"pendo|gong|outreach|salesloft|apollo)\.(com|io)\b",
+    re.IGNORECASE,
+)
+
+# vendor-independence: brand / SDK / platform slugs that lock cognition
+WING3_VENDOR_BLACKLIST = re.compile(
+    r"\b(salesforce|hubspot|marketo|pardot|mailchimp|intercom|drift|"
+    r"klaviyo|sendgrid|mailgun|amplitude|mixpanel|pendo|gong|"
+    r"outreach\.io|salesloft|apollo\.io|zendesk|freshworks)\b",
+    re.IGNORECASE,
+)
+
+# transferability: stack-locked tooling instructions
+WING3_STACK_LOCKED_PATTERN = re.compile(
+    r"\b(npm install|pip install|composer require|gem install|"
+    r"cargo add|yarn add|pnpm add|bundle add)\s+[\w@/.-]+",
+    re.IGNORECASE,
+)
+
+# channel-agnosticism: channel-specific tactical prescriptions
+WING3_CHANNEL_TACTIC_PATTERN = re.compile(
+    r"\b(email subject line|tweet length|linkedin (post|ad)|"
+    r"facebook ad|google ads?|tiktok (post|video)|instagram (post|reel)|"
+    r"sms character limit|cold email template)\b",
+    re.IGNORECASE,
+)
+
+# --- Wing-4 Money/Strategy/Ops cognition-boundary patterns (council Q7 / J2) ---
+# Triggered only when a skill's context_spine declares a Wing-4 slot.
+# See docs/contracts/adr-wing4-context-spine.md and
+# agents/roadmaps/road-to-money-strategy-ops.md § J2.
+WING4_SPINE_SLOTS = {"fiscal-period", "org-stage", "regulatory-regime"}
+
+# agent-operability: external finance / HR / legal SaaS URLs
+WING4_SAAS_URL_PATTERN = re.compile(
+    r"https?://[\w.-]*\.(quickbooks|intuit|netsuite|xero|sage|"
+    r"carta|pulley|gusto|bamboohr|lattice|15five|justworks|"
+    r"docusign|ironclad|onetrust|rippling|workday|deel|"
+    r"namely|adp|paychex|trinet|hibob|cultureamp)\.(com|io|co)\b",
+    re.IGNORECASE,
+)
+
+# vendor-independence: finance / HR / legal brand / SDK slugs
+WING4_VENDOR_BLACKLIST = re.compile(
+    r"\b(quickbooks|netsuite|xero|sage intacct|"
+    r"carta|pulley|gusto|bamboohr|lattice|15five|justworks|"
+    r"docusign|ironclad|onetrust|rippling|workday|deel|"
+    r"namely|adp|paychex|trinet|hibob|culture amp)\b",
+    re.IGNORECASE,
+)
+
+# stage-agnosticism: prescriptive stage-specific thresholds that lock cognition
+# Catches hardcoded runway / ARR / burn / team-size prescriptions tied to a
+# specific funding stage. Framework-style framing ("read the org-stage slot",
+# "applies across seed and public") passes; hard prescriptions ("18 months of
+# runway", "Series A teams must hire") fire.
+WING4_STAGE_AGNOSTIC_PATTERN = re.compile(
+    r"(?:"
+    r"\b\d+\s+months?\s+of\s+runway\b"
+    r"|\brunway\s+of\s+at\s+least\s+\d+\s+months?\b"
+    r"|\bminimum\s+runway\s+of\s+\d+\b"
+    r"|\b(?:seed|series\s+[a-d]|growth|pre-?ipo|post-?ipo)[-\s]stage\s+"
+    r"(?:companies|startups|teams|founders|orgs)\s+(?:must|should|always|never)\b"
+    r"|\bteam\s+of\s+\d+\s+(?:or\s+more|or\s+fewer)\b"
+    r"|\b(?:arr|mrr|burn\s+rate)\s+(?:of|over|under|above|below)\s+\$\d+"
+    r")",
+    re.IGNORECASE,
+)
+
+
+@dataclass
+class Issue:
+    severity: Severity
+    code: str
+    message: str
+
+
+@dataclass
+class LintResult:
+    file: str
+    artifact_type: ArtifactType
+    status: Literal["pass", "pass_with_warnings", "fail"]
+    issues: List[Issue]
+    suggestions: List[str]
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+# --- Role-contract anchor cache (see road-to-role-modes Phase 1) ---
+# Populated lazily so the linter stays fast when the guideline is absent.
+_ROLE_CONTRACT_CANDIDATES = (
+    Path("docs/guidelines/agent-infra/role-contracts.md"),
+)
+_ROLE_CONTRACT_SLUGS_CACHE: Optional[set[str]] = None
+
+
+def _load_role_contract_slugs() -> set[str]:
+    """Return the set of H3 mode slugs defined in role-contracts.md.
+
+    Empty set if the guideline cannot be found — callers MUST treat an
+    empty cache as "no data" and skip the check rather than flagging
+    every reference as broken.
+    """
+    global _ROLE_CONTRACT_SLUGS_CACHE
+    if _ROLE_CONTRACT_SLUGS_CACHE is not None:
+        return _ROLE_CONTRACT_SLUGS_CACHE
+    slugs: set[str] = set()
+    for candidate in _ROLE_CONTRACT_CANDIDATES:
+        if not candidate.exists():
+            continue
+        try:
+            text = candidate.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        in_skeletons = False
+        for line in text.splitlines():
+            if line.startswith("## "):
+                in_skeletons = line.strip().lower().startswith(
+                    "## contract skeletons"
+                )
+                continue
+            if in_skeletons and line.startswith("### "):
+                name = line[4:].strip().lower()
+                slugs.add(re.sub(r"[^a-z0-9]+", "-", name).strip("-"))
+        if slugs:
+            break
+    _ROLE_CONTRACT_SLUGS_CACHE = slugs
+    return slugs
+
+
+_ROLE_CONTRACT_REF_PATTERN = re.compile(
+    r"role-contracts\.md#([a-z0-9][a-z0-9-]*)", re.IGNORECASE
+)
+
+
+def lint_role_contract_refs(text: str) -> List[Issue]:
+    """Warn if a file references `role-contracts.md#<slug>` for a mode
+    that does not exist as an H3 heading in the guideline. No-op when
+    the guideline is missing or declares no modes (bootstrap safety).
+    """
+    slugs = _load_role_contract_slugs()
+    if not slugs:
+        return []
+    issues: List[Issue] = []
+    seen: set[str] = set()
+    for match in _ROLE_CONTRACT_REF_PATTERN.finditer(text):
+        slug = match.group(1).lower()
+        if slug in seen:
+            continue
+        seen.add(slug)
+        if slug not in slugs:
+            issues.append(Issue(
+                "warning", "unknown_role_contract",
+                f"References role-contracts.md#{slug} but no such "
+                f"mode is defined in the guideline (known: "
+                f"{', '.join(sorted(slugs))})",
+            ))
+    return issues
+
+
+def extract_sections(text: str) -> set[str]:
+    return {match.group(1).strip() for match in SECTION_PATTERN.finditer(text)}
+
+
+def _count_code_blocks(text: str) -> int:
+    """Return the number of fenced code blocks (``` … ```) in *text*."""
+    fence_count = 0
+    for line in text.splitlines():
+        stripped = line.lstrip()
+        if stripped.startswith("```"):
+            fence_count += 1
+    return fence_count // 2
+
+
+def _fenced_content_ratio(text: str) -> float:
+    """Return the fraction of non-empty lines that sit inside fenced blocks.
+
+    Retained as a helper for backwards compatibility; the size gates use
+    :func:`_density_score` from the structural model instead (Phase 3 of
+    road-to-structural-linter-reform).
+    """
+    inside = False
+    fenced_lines = 0
+    non_empty = 0
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            inside = not inside
+            if stripped:
+                non_empty += 1
+            continue
+        if stripped:
+            non_empty += 1
+            if inside:
+                fenced_lines += 1
+    if non_empty == 0:
+        return 0.0
+    return fenced_lines / non_empty
+
+
+# --- Structural-density model (docs/contracts/linter-structural-model.md) ---
+# Replaces the raw line/word/fenced-ratio gates with four primitives that
+# distinguish complexity from bloat. Calibrated 2026-05-08 against the full
+# 310-artefact corpus (agents/runtime/density/snapshot.jsonl).
+
+PROCEDURE_HEADING_PATTERN = re.compile(
+    r"^##\s+Procedure(\s*[:\u2014\-].*)?\s*$", re.MULTILINE
+)
+COMMAND_FRONTMATTER_DELEGATION_KEYS = ("cluster:", "routes_to:")
+MD_LINK_PATTERN = re.compile(r"\[[^\]]+\]\(([^)]+\.md[^)]*)\)")
+
+
+def _density_score(text: str) -> float:
+    """Return structural density 0.0–1.0 — see docs/contracts/linter-structural-model.md.
+
+    density = structured_lines / non_blank_lines, where structured_lines =
+    fenced + table + bullet + numbered + heading. Higher = more structured
+    (catalogue, table, code, list); lower = prose-dominant.
+    """
+    inside_fence = False
+    structured = 0
+    non_blank = 0
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if not stripped:
+            continue
+        non_blank += 1
+        if stripped.startswith("```"):
+            inside_fence = not inside_fence
+            structured += 1
+            continue
+        if inside_fence:
+            structured += 1
+            continue
+        if stripped.startswith("#"):
+            structured += 1
+            continue
+        if stripped.startswith("|") and stripped.endswith("|"):
+            structured += 1
+            continue
+        if stripped.startswith(("- ", "* ", "+ ")):
+            structured += 1
+            continue
+        if re.match(r"^\d+\.\s", stripped):
+            structured += 1
+            continue
+    if non_blank == 0:
+        return 0.0
+    return round(structured / non_blank, 3)
+
+
+def _count_procedure_sections(text: str) -> int:
+    """Count `## Procedure` (or `## Procedure: <name>`) blocks in *text*."""
+    return len(PROCEDURE_HEADING_PATTERN.findall(text))
+
+
+def _command_delegation_signal(text: str, frontmatter: Optional[str]) -> bool:
+    """Return True when a command has a delegation signal.
+
+    Signals: frontmatter declares ``cluster:`` or ``routes_to:`` — OR — the
+    body contains ≥ 3 markdown links to other ``.md`` files. Either signal
+    is sufficient (council review 2026-05-08).
+    """
+    if frontmatter:
+        for key in COMMAND_FRONTMATTER_DELEGATION_KEYS:
+            if re.search(rf"^{re.escape(key)}", frontmatter, re.MULTILINE):
+                return True
+    if len(MD_LINK_PATTERN.findall(text)) >= 3:
+        return True
+    return False
+
+
+def _strip_markdown_for_check(text: str) -> str:
+    """Strip fenced code, inline code spans, and markdown links so heuristic
+    regex matches operate on prose only.
+
+    Used by rule-body heuristics whose targets (e.g. ``procedural_rule``)
+    must not flip on legitimate skill pointers like ``[git-workflow](…)``
+    or ``` `skill:symfony-workflow` ```. Frontmatter is handled by the
+    caller via ``text.split("---", 2)[-1]``.
+    """
+    text = re.sub(r"```[^\n]*\n.*?```", "", text, flags=re.DOTALL)
+    text = re.sub(r"`[^`\n]+`", "", text)
+    text = re.sub(r"\[[^\]]*\]\([^)]*\)", "", text)
+    return text
+
+
+def _iron_law_blocks(text: str) -> int:
+    """Count fenced blocks that look like verbatim Iron-Law imperatives.
+
+    Heuristic: fenced block whose body has ≥ 30 alphabetical chars and
+    ≥ 60 % uppercase across ≥ 1 non-empty line. The 30-char floor filters
+    short ALL-CAPS markers (``OK``, ``WIP``); the 60 %-uppercase floor
+    catches verbatim imperatives (``NEVER COMMIT.``).
+    """
+    blocks = 0
+    inside = False
+    body: list[str] = []
+    for raw in text.splitlines():
+        if raw.strip().startswith("```"):
+            if inside and body:
+                non_empty = [b for b in body if b.strip()]
+                letters = "".join(non_empty)
+                upper = sum(1 for c in letters if c.isalpha() and c.isupper())
+                total = sum(1 for c in letters if c.isalpha())
+                if total >= 30 and upper / total >= 0.6 and non_empty:
+                    blocks += 1
+            inside = not inside
+            body = []
+            continue
+        if inside:
+            body.append(raw)
+    return blocks
+
+
+def extract_description(text: str) -> Optional[str]:
+    frontmatter = FRONTMATTER_PATTERN.search(text)
+    if not frontmatter:
+        return None
+    description = DESCRIPTION_PATTERN.search(frontmatter.group(1))
+    return description.group(1).strip() if description else None
+
+
+NAME_PATTERN = re.compile(r'^name:\s*"?(.*?)"?\s*$', re.MULTILINE)
+DISABLE_MODEL_PATTERN = re.compile(r'^disable-model-invocation:\s*"?(true|false)"?\s*$', re.MULTILINE)
+
+
+def detect_artifact_type(path: Path, text: str) -> ArtifactType:
+    path_str = str(path).lower()
+    has_skill_heading = "## When to use" in text and "## Procedure" in text
+
+    # A file inside a /commands/ tree is a command — the commands tree wins,
+    # even for a cluster head literally named `skill.md` or a sub-command under
+    # a `skills/` cluster dir (e.g. /commands/skills/discover.md). The only
+    # /commands/ file that is NOT a command is a nested skill body, which is
+    # always `SKILL.md` (case-sensitive — command files are lowercase).
+    if "/commands/" in path_str and path.name != "SKILL.md":
+        return "command"
+    # Skills: a SKILL.md body, or anything under a /skills/ tree.
+    if path.name.lower() == "skill.md" or "/skills/" in path_str:
+        return "skill"
+    if "/rules/" in path_str:
+        return "rule"
+    if "/guidelines/" in path_str:
+        return "guideline"
+    if "/personas/" in path_str:
+        return "persona"
+    if "/user-types/" in path_str:
+        return "user-type"
+    if has_skill_heading:
+        return "skill"
+    return "unknown"
+
+
+def classify_status(issues: List[Issue]) -> Literal["pass", "pass_with_warnings", "fail"]:
+    severities = {issue.severity for issue in issues}
+    if "error" in severities:
+        return "fail"
+    if "warning" in severities:
+        return "pass_with_warnings"
+    return "pass"
+
+
+
+def extract_section_block(text: str, section_name: str) -> str:
+    pattern = re.compile(
+        rf"^##\s+{re.escape(section_name)}\s*$" r"(.*?)(?=^##\s+|\Z)",
+        re.MULTILINE | re.DOTALL,
+    )
+    match = pattern.search(text)
+    return match.group(1).strip() if match else ""
+
+
+def parse_ordered_list_items(text: str) -> list[str]:
+    return [line.strip() for line in text.splitlines() if re.match(r"^\s*\d+\.\s+", line)]
+
+
+def count_bullets(text: str) -> int:
+    return sum(1 for line in text.splitlines() if re.match(r"^\s*[*-]\s+", line))
+
+
+def has_validation_step(procedure_block: str) -> bool:
+    lowered = procedure_block.lower()
+    if "validate" in lowered or "validation" in lowered:
+        return True
+    good_signals = [
+        "expected", "status code", "no errors", "appears in", "exact check", "concrete checks",
+        "verify", "confirm", "must pass", "must fail", "assert", "check that", "ensure",
+        "run test", "run phpstan", "run ecs", "run rector", "lint", "passes",
+        "exit code", "should return", "should contain", "must contain", "must return",
+    ]
+    return any(signal in lowered for signal in good_signals)
+
+
+_INSPECT_VERB_PATTERN = re.compile(
+    r"\b(?:"
+    # Direct inspection
+    r"inspect|examine|audit|survey"
+    # Read / look
+    r"|read|look\s+at"
+    # Check (word-boundary — matches "check that", "check current", "check what")
+    r"|check"
+    # Review (broad — matches "review existing", "review the failures")
+    r"|review"
+    # Comprehension / orientation
+    r"|understand|identify|analyze|analyse"
+    # Discovery
+    r"|detect|gather|discover"
+    r")\b",
+    re.IGNORECASE,
+)
+
+
+def has_inspect_step(procedure_block: str) -> bool:
+    """Return True if the procedure block opens with an inspect / read step.
+
+    Corpus-driven verb list (see docs/contracts/linter-structural-model.md):
+    the first ordered step in a skill procedure should orient the agent in
+    the live system — read existing code, examine current state, detect
+    stack — before mutating anything. Regex uses word boundaries to avoid
+    substring matches inside unrelated words (e.g. ``read`` inside
+    ``already``).
+    """
+    return bool(_INSPECT_VERB_PATTERN.search(procedure_block))
+
+
+def find_vague_validation(text: str) -> list[str]:
+    hits: list[str] = []
+    for pattern in VAGUE_VALIDATION_PATTERNS:
+        for match in re.finditer(pattern, text, re.IGNORECASE):
+            hits.append(match.group(0))
+    return hits
+
+
+def is_probably_too_broad(text: str, description: Optional[str]) -> bool:
+    # Only check description and "When to use" for broad signals — not the entire text
+    haystacks: list[str] = []
+    if description:
+        haystacks.append(description.lower())
+    when_block = extract_section_block(text, "When to use")
+    if when_block:
+        haystacks.append(when_block.lower())
+    if not haystacks:
+        return False
+    combined = "\n".join(haystacks)
+    broad_signals = ["everything about", "general purpose", "general-purpose", "all markdown", "helper for everything"]
+    return any(signal in combined for signal in broad_signals)
+
+
+def dedupe_preserve_order(items: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for item in items:
+        if item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result
+
+
+def section_matches(required: str, sections: set[str]) -> bool:
+    """Check if a required section name matches any extracted section, supporting aliases and prefix matching."""
+    # Direct match
+    if required in sections:
+        return True
+    # Alias match (e.g. "Gotcha" matches "Gotchas")
+    aliases = SECTION_ALIASES.get(required, set())
+    if aliases & sections:
+        return True
+    # Prefix match (e.g. "Procedure" matches "Procedure: Create X")
+    for s in sections:
+        if s.startswith(required + ":") or s.startswith(required + " "):
+            return True
+    return False
+
+
+def find_procedure_block(text: str) -> Optional[str]:
+    """Find the procedure section block, supporting prefix-named variants."""
+    block = extract_section_block(text, "Procedure")
+    if block:
+        return block
+    # Try prefix match: find "## Procedure: ..." or "## Procedure " headings
+    match = re.search(r"^##\s+Procedure[:\s]", text, re.MULTILINE)
+    if match:
+        # Extract from this heading to the next ## heading
+        start = match.end()
+        next_heading = re.search(r"^##\s+", text[start:], re.MULTILINE)
+        if next_heading:
+            return text[start:start + next_heading.start()].strip()
+        return text[start:].strip()
+    return None
+
+
+def lint_skill(path: Path, text: str) -> LintResult:
+    issues: List[Issue] = []
+    suggestions: List[str] = []
+
+    sections = extract_sections(text)
+    description = extract_description(text)
+
+    for section in REQUIRED_SKILL_SECTIONS:
+        if not section_matches(section, sections):
+            issues.append(Issue("error", "missing_section", f"Missing required section: {section}"))
+
+    for section in RECOMMENDED_SKILL_SECTIONS:
+        if not section_matches(section, sections):
+            issues.append(Issue("warning", "missing_recommended_section", f"Missing recommended section: {section}"))
+
+    if description:
+        if len(description) > 200:
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
+        for pattern in TRIGGER_WARNING_PATTERNS:
+            if re.search(pattern, description, re.IGNORECASE):
+                issues.append(Issue("warning", "weak_trigger", f"Description looks too generic: {description}"))
+                break
+    else:
+        issues.append(Issue("warning", "missing_description", "Frontmatter description is missing or unreadable"))
+
+    # --- Bare-noun name check ---
+    skill_name = path.parent.name if path.name == "SKILL.md" else path.stem
+    if skill_name and "-" not in skill_name and len(skill_name) >= 3:
+        # Single word without qualifier — likely too generic
+        ALLOWED_BARE_NOUNS = {"database", "devcontainer", "docker", "eloquent", "flux", "forecasting",
+                              "grafana", "laravel", "livewire", "markitdown", "mcp", "openapi",
+                              "performance", "security", "terraform", "terragrunt", "traefik",
+                              "websocket"}
+        if skill_name.lower() not in ALLOWED_BARE_NOUNS:
+            issues.append(Issue("warning", "bare_noun_name",
+                                f"Bare-noun skill name `{skill_name}` — consider adding a qualifier (e.g., `{skill_name}-management`)"))
+
+    # --- Status lifecycle check ---
+    frontmatter = extract_frontmatter(text)
+    if frontmatter:
+        status_match = STATUS_PATTERN.search(frontmatter)
+        if status_match:
+            status = status_match.group(1)
+            if status == "deprecated":
+                replaced_by = extract_frontmatter_field(frontmatter, REPLACED_BY_PATTERN)
+                msg = f"Skill is deprecated"
+                if replaced_by:
+                    msg += f" (replaced by: {replaced_by})"
+                issues.append(Issue("warning", "deprecated_skill", msg))
+            elif status == "superseded":
+                replaced_by = extract_frontmatter_field(frontmatter, REPLACED_BY_PATTERN)
+                msg = f"Skill is superseded — should be removed"
+                if replaced_by:
+                    msg += f" (replaced by: {replaced_by})"
+                issues.append(Issue("warning", "superseded_skill", msg))
+
+        # --- Execution metadata check ---
+        execution = parse_execution_block(frontmatter)
+        if execution is not None:
+            issues.extend(lint_execution_metadata(execution))
+
+        # --- Senior-tier required-block check (skill-quality.md § Senior-Tier Required Structure) ---
+        tier_match = TIER_PATTERN.search(frontmatter)
+        if tier_match and tier_match.group(1) == "senior":
+            issues.extend(lint_senior_tier_blocks(text))
+
+        # --- Wing-3 GTM cognition-boundary check (council Q7 / adr-gtm-context-spine.md) ---
+        spine_slots = parse_context_spine(frontmatter)
+        if spine_slots and any(s in WING3_SPINE_SLOTS for s in spine_slots):
+            issues.extend(lint_wing3_boundaries(text))
+
+        # --- Wing-4 Money/Strategy/Ops cognition-boundary check (council Q7 / J2) ---
+        if spine_slots and any(s in WING4_SPINE_SLOTS for s in spine_slots):
+            issues.extend(lint_wing4_boundaries(text))
+
+    procedure_block = find_procedure_block(text)
+    if procedure_block is not None:
+        if not procedure_block:
+            issues.append(Issue("error", "empty_procedure", "Procedure section is empty"))
+        else:
+            # Check for ordered steps OR sub-headings as structural indicators
+            has_ordered = ORDERED_STEP_PATTERN.search(procedure_block)
+            has_subheadings = bool(re.search(r"^###\s+", procedure_block, re.MULTILINE))
+            if not has_ordered and not has_subheadings:
+                issues.append(Issue("error", "unordered_procedure", "Procedure has no ordered steps or sub-headings"))
+            meaningful_steps = len(ORDERED_STEP_PATTERN.findall(procedure_block))
+            if meaningful_steps < 3:
+                issues.append(Issue("warning", "short_procedure", "Procedure has fewer than 3 ordered steps"))
+            # Check validation in procedure block OR in the full skill text
+            # (some skills have ### Validate under a sibling ## section)
+            if not has_validation_step(procedure_block) and not has_validation_step(text):
+                issues.append(Issue("error", "missing_validation", "Skill lacks a concrete validation step"))
+            vague_hits = find_vague_validation(procedure_block)
+            for hit in vague_hits:
+                issues.append(Issue("error", "vague_validation", f"Vague validation detected: {hit}"))
+            if not has_inspect_step(procedure_block):
+                issues.append(Issue("warning", "missing_inspect_step", "Procedure has no explicit inspect/check step"))
+
+    if "## Output format" in text:
+        output_block = extract_section_block(text, "Output format")
+        if not output_block or len(parse_ordered_list_items(output_block)) < 2:
+            issues.append(Issue("warning", "weak_output_format", "Output format should contain at least 2 ordered requirements"))
+            suggestions.append("Add 2-4 ordered output requirements")
+    else:
+        suggestions.append("Add an Output format section with ordered response constraints")
+
+    # Check Gotcha/Gotchas section (alias support)
+    gotcha_block = extract_section_block(text, "Gotchas") or extract_section_block(text, "Gotcha")
+    if gotcha_block:
+        if count_bullets(gotcha_block) < 1:
+            issues.append(Issue("warning", "weak_gotchas", "Gotchas should contain at least one realistic failure mode"))
+    else:
+        suggestions.append("Add at least one realistic failure pattern to Gotchas")
+
+    if "## Do NOT" in text:
+        do_not_block = extract_section_block(text, "Do NOT")
+        if count_bullets(do_not_block) < 1:
+            issues.append(Issue("warning", "weak_do_not", "Do NOT should contain at least one enforceable constraint"))
+    else:
+        suggestions.append("Add at least one enforceable Do NOT constraint")
+
+    if is_probably_too_broad(text, description):
+        issues.append(Issue("warning", "broad_scope", "Skill scope appears broad and may need splitting"))
+        suggestions.append("Narrow the trigger or split unrelated workflows")
+
+    # --- Developer judgment check for assisted skills ---
+    fm = extract_frontmatter(text)
+    exec_block = parse_execution_block(fm) if fm else None
+    exec_type = exec_block.get("type", "") if exec_block else ""
+    if exec_type == "assisted" and procedure_block:
+        validation_terms = ["validat", "check", "verify", "confirm", "challenge",
+                          "existing", "duplicate", "contradict", "fit", "misfit"]
+        has_validation = any(term in procedure_block.lower() for term in validation_terms)
+        if not has_validation:
+            issues.append(Issue("warning", "missing_validation_step",
+                              "Assisted skill has no validation/challenge step in procedure"))
+            suggestions.append("Add a requirement-checking or validation step before implementation")
+
+    # --- Size check (docs/contracts/linter-structural-model.md) ---
+    # Structural-density gate replaces raw line count (Phase 3 of
+    # road-to-structural-linter-reform, 2026-05-08): warn only when the skill
+    # is *both* large AND prose-dominant OR ships ≥ 2 independently invocable
+    # procedures. Reference catalogues (quality-tools 411 L / density 0.83)
+    # pass; multi-procedure skills are flagged for split.
+    #
+    # Frontmatter opt-out: `meta_skill: true` exempts a skill from the size
+    # warn when the skill's purpose *is* breadth (skill-writing, agent-docs-
+    # writing, skill-reviewer, etc.). Meta-skills inherently bundle multiple
+    # procedures and inline examples.
+    total_lines = len(text.splitlines())
+    is_meta_skill = bool(fm) and re.search(r"^meta_skill:\s*true\s*$", fm, re.MULTILINE)
+    if total_lines > 400 and not is_meta_skill:
+        density = _density_score(text)
+        procedures = _count_procedure_sections(text)
+        if density < 0.6 or procedures >= 2:
+            reason = (
+                f"density {density:.2f} < 0.60"
+                if density < 0.6
+                else f"{procedures} ## Procedure blocks (≥ 2)"
+            )
+            issues.append(Issue(
+                "warning",
+                "skill_too_large",
+                f"Skill has {total_lines} lines and {reason}; review for split "
+                f"(see linter-structural-model contract)",
+            ))
+
+    # --- Pointer-only / guideline-dependent skill detection ---
+    if procedure_block:
+        proc_lines = [line.strip() for line in procedure_block.splitlines() if line.strip()]
+
+        # Delegation patterns: references to external docs instead of own workflow
+        delegation_patterns = re.findall(
+            r"(?:see|read|check|follow|refer\s+to|consult|per|apply\s+.*from)\s+.*"
+            r"(?:guideline|skill|rule|doc|documentation)",
+            procedure_block, re.IGNORECASE)
+        delegation_count = len(delegation_patterns)
+
+        # Action verbs that indicate the skill has its own operational workflow
+        action_verbs = re.findall(
+            r"\b(?:run|execute|create|write|validate|verify|inspect|check|ensure|test|build|"
+            r"generate|compare|extract|parse|detect|fix|update|add|remove|install|configure|"
+            r"deploy|trace|review|map|resolve|measure|confirm)\b",
+            procedure_block, re.IGNORECASE)
+        action_count = len(set(v.lower() for v in action_verbs))
+
+        # Count actual ordered steps
+        meaningful_steps = len(ORDERED_STEP_PATTERN.findall(procedure_block))
+
+        # Thin procedure: few steps AND few lines
+        has_thin_procedure = meaningful_steps < 3 and len(proc_lines) < 8
+
+        # Error: effectively a pointer, not a real skill
+        if delegation_count >= 3 and action_count <= 1 and has_thin_procedure:
+            issues.append(Issue("error", "guideline_dependent_skill",
+                               f"Skill is effectively a pointer to guidelines/docs "
+                               f"({delegation_count} delegations, {action_count} action verbs, "
+                               f"{meaningful_steps} steps) — not an executable workflow"))
+            suggestions.append("Add concrete steps, decision points, and validation directly into the skill")
+        # Warning: likely too dependent on external guidance
+        elif delegation_count >= 2 and action_count <= 2 and has_thin_procedure:
+            issues.append(Issue("warning", "pointer_only_skill",
+                               f"Skill appears too guideline-dependent "
+                               f"({delegation_count} delegations, {action_count} action verbs, "
+                               f"{meaningful_steps} steps) — may lack its own executable workflow"))
+            suggestions.append("Expand the skill so it remains executable without opening a guideline")
+
+    # --- evals.json schema validator ---
+    # When a skill ships sibling `evals/evals.json` (quantitative behavior
+    # eval per skill-writing § 7), validate its shape. Triggers.json is a
+    # separate concern handled elsewhere. All issues here are WARN.
+    issues.extend(validate_evals_json(path))
+
+    return LintResult(
+        file=str(path),
+        artifact_type="skill",
+        status=classify_status(issues),
+        issues=issues,
+        suggestions=dedupe_preserve_order(suggestions),
+    )
+
+
+def validate_evals_json(skill_path: Path) -> list[Issue]:
+    """Validate `{skill_dir}/evals/evals.json` against the schema declared
+    in `skill-writing` § 7. Returns WARN-level issues only; never blocks.
+    Skipped entirely when the file is absent."""
+    evals_path = skill_path.parent / "evals" / "evals.json"
+    if not evals_path.is_file():
+        return []
+    issues: list[Issue] = []
+    try:
+        data = json.loads(evals_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return [Issue("warning", "evals_json_unreadable",
+                      f"evals/evals.json could not be parsed: {exc}")]
+    if not isinstance(data, dict):
+        return [Issue("warning", "evals_json_shape",
+                      "evals/evals.json root must be an object")]
+    if "skill" not in data or not isinstance(data["skill"], str):
+        issues.append(Issue("warning", "evals_json_missing_skill",
+                            "evals/evals.json must declare top-level 'skill' (string)"))
+    scenarios = data.get("scenarios")
+    if not isinstance(scenarios, list) or len(scenarios) < 1:
+        issues.append(Issue("warning", "evals_json_no_scenarios",
+                            "evals/evals.json must declare 'scenarios' (non-empty array)"))
+        return issues
+    valid_kinds = {"contains", "file_exists", "rubric"}
+    for idx, scenario in enumerate(scenarios):
+        loc = f"scenarios[{idx}]"
+        if not isinstance(scenario, dict):
+            issues.append(Issue("warning", "evals_json_scenario_shape",
+                                f"{loc} must be an object"))
+            continue
+        for key in ("id", "prompt"):
+            if key not in scenario or not isinstance(scenario[key], str) or not scenario[key].strip():
+                issues.append(Issue("warning", "evals_json_scenario_missing_field",
+                                    f"{loc} missing required string field '{key}'"))
+        assertions = scenario.get("assertions")
+        if not isinstance(assertions, list) or len(assertions) < 1:
+            issues.append(Issue("warning", "evals_json_scenario_no_assertions",
+                                f"{loc}.assertions must be a non-empty array"))
+            continue
+        for a_idx, assertion in enumerate(assertions):
+            a_loc = f"{loc}.assertions[{a_idx}]"
+            if not isinstance(assertion, dict):
+                issues.append(Issue("warning", "evals_json_assertion_shape",
+                                    f"{a_loc} must be an object"))
+                continue
+            kind = assertion.get("kind")
+            if kind not in valid_kinds:
+                issues.append(Issue("warning", "evals_json_assertion_kind",
+                                    f"{a_loc}.kind must be one of {sorted(valid_kinds)}, got {kind!r}"))
+                continue
+            required_field = {"contains": "value", "file_exists": "path", "rubric": "criterion"}[kind]
+            if required_field not in assertion or not isinstance(assertion[required_field], str):
+                issues.append(Issue("warning", "evals_json_assertion_missing_field",
+                                    f"{a_loc} (kind={kind}) missing required string field '{required_field}'"))
+    return issues
+
+
+def extract_frontmatter(text: str) -> Optional[str]:
+    match = FRONTMATTER_PATTERN.search(text)
+    return match.group(1) if match else None
+
+
+def _parse_trust_level(frontmatter: str) -> Optional[str]:
+    """Parse `trust.level:` from the nested `trust:` mapping in frontmatter.
+
+    Returns the level string (e.g. ``"core"``, ``"advisory"``) or ``None``
+    if absent. Stdlib-only — mirrors the line-walking approach of
+    ``_parse_yaml_list`` so the linter stays pyyaml-free.
+    """
+    lines = frontmatter.splitlines()
+    in_block = False
+    for line in lines:
+        if not in_block:
+            if line.startswith("trust:"):
+                rhs = line[len("trust:"):].strip()
+                if rhs == "":
+                    in_block = True
+            continue
+        if line.startswith("  level:"):
+            return line[len("  level:"):].strip().strip('"').strip("'")
+        if line.startswith("  "):
+            continue
+        break
+    return None
+
+
+def _parse_yaml_list(frontmatter: str, key: str) -> Optional[list]:
+    """Parse a simple top-level YAML list `key:` from frontmatter.
+
+    Supports the two shapes we emit in rule frontmatter:
+      triggers:
+        - keyword: "foo"
+        - phrase: "bar baz"
+      routes_to:
+        - skill:php-coder
+        - guideline:agent-infra/asking-and-brevity-examples
+
+    Returns ``None`` if the key is absent (so the caller can distinguish
+    "missing" from "empty"); returns ``[]`` for an explicitly empty list.
+    """
+    lines = frontmatter.splitlines()
+    out: list = []
+    in_block = False
+    for line in lines:
+        if not in_block:
+            if line.startswith(f"{key}:"):
+                rhs = line[len(key) + 1:].strip()
+                if rhs in ("", "[]"):
+                    if rhs == "[]":
+                        return []
+                    in_block = True
+                else:
+                    return None  # unexpected scalar shape
+            continue
+        if line.startswith("  - "):
+            item = line[4:].strip()
+            if ":" in item and not item.startswith(("'", '"')):
+                k, _, v = item.partition(":")
+                out.append({k.strip(): v.strip().strip('"').strip("'")})
+            else:
+                out.append(item.strip('"').strip("'"))
+        elif line.strip() == "" or line.startswith("    "):
+            continue
+        else:
+            break
+    return out if in_block else None
+
+
+def lint_router_frontmatter(rule_id: str, frontmatter: str,
+                             rule_type: Optional[str]) -> List[Issue]:
+    """Validate `triggers:` / `routes_to:` per docs/contracts/rule-router.md.
+
+    Strict checks (always errors): kernel rules MUST NOT carry router fields;
+    `triggers:` items must use one allowed key; `routes_to:` items must
+    follow `kind:id` with kind ∈ {skill, guideline} and the target file
+    must exist on disk.
+
+    Lenient checks (info-level until Phase 4 migrations land): non-kernel
+    rules without `triggers:` / `routes_to:` get an informational note,
+    not an error — the existing description-matching path still works.
+
+    Trust-tier carve-out: rules with ``trust.level: core`` are exempt from
+    the ``router_routes_to_missing`` migration hint — they are authoritative
+    by design and their body legitimately lives inline.
+    """
+    issues: List[Issue] = []
+    triggers = _parse_yaml_list(frontmatter, "triggers")
+    routes_to = _parse_yaml_list(frontmatter, "routes_to")
+
+    # Manual rules are reference-only — not auto-injected, not router-routed
+    # (ADR-004). Skip router validation so legacy triggers/routes_to fields
+    # remain documented in the rule body without forcing maintenance.
+    if rule_type == "manual":
+        return issues
+
+    is_kernel = rule_id in KERNEL_RULE_IDS or rule_type == "always"
+
+    if is_kernel:
+        if triggers is not None:
+            issues.append(Issue("error", "kernel_has_triggers",
+                "Kernel rules MUST NOT declare triggers: (kernel is unconditional)"))
+        if routes_to is not None:
+            issues.append(Issue("error", "kernel_has_routes_to",
+                "Kernel rules MUST NOT declare routes_to: (kernel body stays inline)"))
+        return issues
+
+    # Non-kernel rule path
+    if triggers is None:
+        issues.append(Issue("info", "router_triggers_missing",
+            "Non-kernel rule has no triggers: — falls back to description matching "
+            "until Phase 4 migration lands"))
+    else:
+        for idx, item in enumerate(triggers):
+            if not isinstance(item, dict) or len(item) != 1:
+                issues.append(Issue("error", "trigger_shape_invalid",
+                    f"triggers[{idx}] must be a single-key mapping"))
+                continue
+            (k,) = item.keys()
+            if k not in ROUTER_ALLOWED_TRIGGER_KEYS:
+                allowed = ", ".join(sorted(ROUTER_ALLOWED_TRIGGER_KEYS))
+                issues.append(Issue("error", "trigger_key_unknown",
+                    f"triggers[{idx}] key '{k}' not in allowed set ({allowed})"))
+
+    if routes_to is None:
+        # Trust-tier carve-out: rules pinned at trust.level: core are
+        # authoritative — their body IS the behavior and may legitimately
+        # live inline without a routes_to: delegation. The Phase 4
+        # migration hint applies only to lower-trust rules.
+        trust_level = _parse_trust_level(frontmatter)
+        if trust_level != "core":
+            issues.append(Issue("info", "router_routes_to_missing",
+                "Non-kernel rule has no routes_to: — body should migrate to skill / "
+                "guideline in Phase 4"))
+    else:
+        repo_root = Path(__file__).resolve().parent.parent.parent
+        for idx, item in enumerate(routes_to):
+            if not isinstance(item, str) or ":" not in item:
+                issues.append(Issue("error", "route_shape_invalid",
+                    f"routes_to[{idx}] must be 'kind:id'"))
+                continue
+            kind, _, target_id = item.partition(":")
+            # Multi-root aware (ADR-017): resolve logical paths via every
+            # source root so kernel rules keep routing to skills/commands
+            # that moved into packages/*/.
+            target: Optional[Path] = None
+            if kind == "skill":
+                target = resolve_logical(f"skills/{target_id}/SKILL.md")
+            elif kind == "guideline":
+                gpath = repo_root / "docs" / "guidelines" / f"{target_id}.md"
+                target = gpath if gpath.exists() else None
+            elif kind == "command":
+                target = resolve_logical(f"commands/{target_id}.md")
+            elif kind == "contract":
+                # Contracts live in two places: stable host docs in
+                # docs/contracts/ and load-bearing flows under
+                # contexts/contracts/ inside any source root (road-to-path-fixes
+                # P4 / Council R2). Try both before failing.
+                cpath = repo_root / "docs" / "contracts" / f"{target_id}.md"
+                if cpath.exists():
+                    target = cpath
+                else:
+                    target = resolve_logical(f"contexts/contracts/{target_id}.md")
+            else:
+                issues.append(Issue("error", "route_kind_unknown",
+                    f"routes_to[{idx}] kind '{kind}' must be 'skill', 'guideline', 'command', or 'contract'"))
+                continue
+            if target is None or not target.exists():
+                issues.append(Issue("error", "route_target_missing",
+                    f"routes_to[{idx}] target '{item}' not found under any artefact root"))
+    return issues
+
+
+def extract_frontmatter_field(frontmatter: str, pattern: re.Pattern[str]) -> Optional[str]:
+    match = pattern.search(frontmatter)
+    return match.group(1).strip() if match else None
+
+
+def parse_execution_block(frontmatter: str) -> Optional[dict]:
+    """Parse the execution block from YAML frontmatter.
+
+    Uses simple line-based parsing to avoid requiring PyYAML.
+    Returns None if no execution block is present.
+    """
+    lines = frontmatter.splitlines()
+    exec_start = None
+    for i, line in enumerate(lines):
+        if re.match(r'^execution:\s*$', line):
+            exec_start = i
+            break
+    if exec_start is None:
+        return None
+
+    result: dict = {}
+    for line in lines[exec_start + 1:]:
+        # Stop at next top-level key (no indentation)
+        if line and not line[0].isspace():
+            break
+        stripped = line.strip()
+        if not stripped or stripped.startswith('#'):
+            continue
+        # Handle list items (for allowed_tools)
+        if stripped.startswith('- '):
+            if '_current_list' in result:
+                result[result['_current_list']].append(stripped[2:].strip().strip('"').strip("'"))
+            continue
+        # Handle key: value pairs
+        match = re.match(r'^(\w+):\s*(.*?)\s*$', stripped)
+        if match:
+            key = match.group(1)
+            value = match.group(2).strip('"').strip("'")
+            if value == '[]':
+                result[key] = []
+                result['_current_list'] = key
+            elif re.match(r'^\[.*\]$', value):
+                # Inline YAML/JSON array like [github] or ["github", "jira"]
+                inner = value[1:-1].strip()
+                if inner:
+                    items = [item.strip().strip('"').strip("'") for item in inner.split(',')]
+                    result[key] = items
+                else:
+                    result[key] = []
+                result['_current_list'] = key
+            elif value == '':
+                # Could be a list starting on next line
+                result[key] = []
+                result['_current_list'] = key
+            else:
+                # Try to parse as int
+                try:
+                    result[key] = int(value)
+                except ValueError:
+                    result[key] = value
+                result.pop('_current_list', None)
+
+    result.pop('_current_list', None)
+    return result
+
+
+def lint_senior_tier_blocks(text: str) -> List[Issue]:
+    """Validate the four required blocks for `tier: senior` skills.
+
+    Per .agent-src.uncondensed/rules/skill-quality.md § Senior-Tier
+    Required Structure: Context-First lead (description), Related Skills
+    (with WHEN / WHEN NOT lists), Proactive Triggers, Output Artifacts.
+
+    The Context-First lead is checked structurally via description length
+    + content; here we enforce the three section blocks and the WHEN /
+    WHEN NOT two-list pattern inside Related Skills.
+    """
+    issues: List[Issue] = []
+
+    if not SENIOR_RELATED_SKILLS_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_related_skills",
+            "Senior-tier skill missing `## Related Skills` block (skill-quality.md § Senior-Tier Required Structure)",
+        ))
+    else:
+        related_block = extract_section_block(text, "Related Skills") or ""
+        if not SENIOR_RELATED_WHEN_PATTERN.search(related_block):
+            issues.append(Issue(
+                "error",
+                "missing_senior_related_when",
+                "Senior-tier `## Related Skills` block missing `**WHEN to use this**` list",
+            ))
+        if not SENIOR_RELATED_WHEN_NOT_PATTERN.search(related_block):
+            issues.append(Issue(
+                "error",
+                "missing_senior_related_when_not",
+                "Senior-tier `## Related Skills` block missing `**WHEN NOT to use this**` list",
+            ))
+
+    if not SENIOR_PROACTIVE_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_proactive_triggers",
+            "Senior-tier skill missing `## When the agent should load this` block",
+        ))
+
+    if not SENIOR_OUTPUT_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_output_artifacts",
+            "Senior-tier skill missing `## Output` block declaring artifact name + shape",
+        ))
+
+    return issues
+
+
+def parse_context_spine(frontmatter: str) -> Optional[List[str]]:
+    """Parse `context_spine:` from frontmatter.
+
+    Supports the inline form `context_spine: [a, b, c]` (most skills) and
+    the block form via `_parse_yaml_list`. Returns the slot list, ``[]``
+    for an explicitly empty array, or ``None`` if the key is absent.
+    """
+    match = CONTEXT_SPINE_INLINE_PATTERN.search(frontmatter)
+    if match is not None:
+        inner = match.group(1).strip()
+        if not inner:
+            return []
+        return [s.strip().strip('"').strip("'") for s in inner.split(",") if s.strip()]
+    block = _parse_yaml_list(frontmatter, "context_spine")
+    return block
+
+
+def _strip_wing3_carve_outs(text: str) -> str:
+    """Remove fenced code, inline backticks, the ``## Do NOT`` block, and
+    ``**WHEN NOT to use this**`` bullets so legitimate citations of vendor
+    names (as off-scope examples) do not trip Wing-3 boundary checks.
+    """
+    text = re.sub(r"```[^\n]*\n.*?```", "", text, flags=re.DOTALL)
+    text = re.sub(r"`[^`]+`", "", text)
+    text = re.sub(
+        r"^##\s+Do NOT\s*$.*?(?=^##\s+|\Z)",
+        "", text, flags=re.MULTILINE | re.DOTALL,
+    )
+    text = re.sub(
+        r"\*\*WHEN NOT to use this\*\*.*?(?=\*\*WHEN|^##\s+|\Z)",
+        "", text, flags=re.DOTALL | re.IGNORECASE,
+    )
+    return text
+
+
+def lint_wing3_boundaries(text: str) -> List[Issue]:
+    """Four Wing-3 GTM cognition-boundary checks.
+
+    Triggered when a skill's ``context_spine`` declares at least one
+    Wing-3 slot (channel-stage, funnel-stage, customer-segment). Enforces
+    council Q7 / iter-2 OQ3 verdict that GTM cognition stays:
+
+    - **agent-operability** — no external SaaS URLs the agent would auth against.
+    - **vendor-independence** — no platform / SDK / brand slugs.
+    - **transferability** — no stack-locked tooling instructions.
+    - **channel-agnosticism** — no channel-specific tactical prescriptions.
+
+    Carve-outs: fenced code, inline backticks, the ``## Do NOT`` block,
+    and ``**WHEN NOT to use this**`` lists — so authors can cite a vendor
+    as off-scope without tripping the linter.
+    """
+    issues: List[Issue] = []
+    body = _strip_wing3_carve_outs(text)
+
+    match = WING3_SAAS_URL_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing3_agent_operability",
+            f"Wing-3 skill cites external SaaS URL `{match.group(0)}` outside "
+            f"carve-outs — cognition skills must operate without SaaS auth "
+            f"(council Q7 boundary)",
+        ))
+
+    match = WING3_VENDOR_BLACKLIST.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing3_vendor_independence",
+            f"Wing-3 skill names vendor `{match.group(0)}` outside carve-outs "
+            f"— keep cognition vendor-agnostic (council Q7 boundary)",
+        ))
+
+    match = WING3_STACK_LOCKED_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing3_transferability",
+            f"Wing-3 skill includes stack-locked instruction `{match.group(0)}` "
+            f"outside carve-outs — cognition should transfer across stacks "
+            f"(council Q7 boundary)",
+        ))
+
+    match = WING3_CHANNEL_TACTIC_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing3_channel_agnosticism",
+            f"Wing-3 skill prescribes channel-specific tactic "
+            f"`{match.group(0)}` outside carve-outs — keep cognition "
+            f"channel-agnostic (council Q7 boundary)",
+        ))
+
+    return issues
+
+
+def lint_wing4_boundaries(text: str) -> List[Issue]:
+    """Four Wing-4 Money/Strategy/Ops cognition-boundary checks.
+
+    Triggered when a skill's ``context_spine`` declares at least one
+    Wing-4 slot (fiscal-period, org-stage, regulatory-regime). Enforces
+    council Q7 / J2 verdict that Money/Strategy/Ops cognition stays:
+
+    - **agent-operability** — no external finance/HR/legal SaaS URLs.
+    - **vendor-independence** — no QuickBooks/Carta/Gusto-class brand slugs.
+    - **transferability** — no stack-locked tooling instructions.
+    - **stage-agnosticism** — no prescriptive stage-specific thresholds.
+
+    Carve-outs are identical to Wing-3: fenced code, inline backticks,
+    the ``## Do NOT`` block, and ``**WHEN NOT to use this**`` lists.
+    Regulatory regime names (GDPR / HIPAA / SOC2 / PCI / CCPA) are
+    cognition-relevant constraints, not vendors — they pass.
+    """
+    issues: List[Issue] = []
+    body = _strip_wing3_carve_outs(text)
+
+    match = WING4_SAAS_URL_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing4_agent_operability",
+            f"Wing-4 skill cites external SaaS URL `{match.group(0)}` outside "
+            f"carve-outs — cognition skills must operate without SaaS auth "
+            f"(council Q7 boundary)",
+        ))
+
+    match = WING4_VENDOR_BLACKLIST.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing4_vendor_independence",
+            f"Wing-4 skill names vendor `{match.group(0)}` outside carve-outs "
+            f"— keep cognition vendor-agnostic (council Q7 boundary)",
+        ))
+
+    match = WING3_STACK_LOCKED_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing4_transferability",
+            f"Wing-4 skill includes stack-locked instruction `{match.group(0)}` "
+            f"outside carve-outs — cognition should transfer across stacks "
+            f"(council Q7 boundary)",
+        ))
+
+    match = WING4_STAGE_AGNOSTIC_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing4_stage_agnosticism",
+            f"Wing-4 skill prescribes stage-locked threshold "
+            f"`{match.group(0)}` outside carve-outs — cognition must "
+            f"transfer across seed and public (council Q7 boundary)",
+        ))
+
+    return issues
+
+
+def lint_execution_metadata(execution: dict) -> List[Issue]:
+    """Validate the execution block of a skill."""
+    issues: List[Issue] = []
+
+    # Validate type
+    exec_type = execution.get("type")
+    if exec_type is not None:
+        if exec_type not in VALID_EXECUTION_TYPES:
+            issues.append(Issue("error", "invalid_execution_type",
+                                f"Invalid execution.type '{exec_type}'; "
+                                f"must be one of: {', '.join(sorted(VALID_EXECUTION_TYPES))}"))
+    else:
+        issues.append(Issue("error", "missing_execution_type",
+                            "Execution block present but missing 'type' field"))
+
+    # Validate handler
+    handler = execution.get("handler")
+    if handler is not None:
+        if handler not in VALID_EXECUTION_HANDLERS:
+            issues.append(Issue("error", "invalid_execution_handler",
+                                f"Invalid execution.handler '{handler}'; "
+                                f"must be one of: {', '.join(sorted(VALID_EXECUTION_HANDLERS))}"))
+
+    # Automated-specific checks
+    if exec_type == "automated":
+        if handler is None or handler == "none":
+            issues.append(Issue("error", "automated_missing_handler",
+                                "Automated execution requires a handler other than 'none'"))
+        safety_mode = execution.get("safety_mode")
+        if safety_mode is None:
+            issues.append(Issue("error", "automated_missing_safety_mode",
+                                "Automated execution requires 'safety_mode: strict'"))
+        elif safety_mode not in VALID_EXECUTION_SAFETY_MODES:
+            issues.append(Issue("error", "invalid_safety_mode",
+                                f"Invalid safety_mode '{safety_mode}'; must be 'strict'"))
+        if "allowed_tools" not in execution:
+            issues.append(Issue("warning", "automated_missing_allowed_tools",
+                                "Automated execution should declare 'allowed_tools' (use [] for none)"))
+
+    # Validate safety_mode if present (even for non-automated)
+    safety_mode = execution.get("safety_mode")
+    if safety_mode is not None and safety_mode not in VALID_EXECUTION_SAFETY_MODES:
+        issues.append(Issue("error", "invalid_safety_mode",
+                            f"Invalid safety_mode '{safety_mode}'; must be 'strict'"))
+
+    # Validate timeout_seconds
+    timeout = execution.get("timeout_seconds")
+    if timeout is not None:
+        if not isinstance(timeout, int) or timeout <= 0:
+            issues.append(Issue("warning", "invalid_timeout",
+                                f"timeout_seconds should be a positive integer, got '{timeout}'"))
+
+    # Validate allowed_tools is a list of strings
+    allowed_tools = execution.get("allowed_tools")
+    if allowed_tools is not None:
+        if not isinstance(allowed_tools, list):
+            issues.append(Issue("error", "invalid_allowed_tools",
+                                "allowed_tools must be a list"))
+        elif not all(isinstance(t, str) for t in allowed_tools):
+            issues.append(Issue("error", "invalid_allowed_tools_entries",
+                                "All entries in allowed_tools must be strings"))
+
+    # Validate command shape if present. Skills that declare `command` are
+    # runtime-executable; skills without it stay in proposal-only mode.
+    command = execution.get("command")
+    if command is not None:
+        if not isinstance(command, list) or not all(isinstance(c, str) for c in command):
+            issues.append(Issue("error", "invalid_command",
+                                "command must be a list of strings (argv form)"))
+        elif len(command) == 0:
+            issues.append(Issue("error", "empty_command",
+                                "command must not be empty"))
+
+    # Check for unknown fields
+    known_fields = VALID_EXECUTION_FIELDS
+    unknown = set(execution.keys()) - known_fields
+    for field in sorted(unknown):
+        issues.append(Issue("warning", "unknown_execution_field",
+                            f"Unknown field in execution block: '{field}'"))
+
+    return issues
+
+
+def lint_rule(path: Path, text: str) -> LintResult:
+    issues: List[Issue] = []
+    suggestions: List[str] = []
+
+    # --- Frontmatter checks ---
+    frontmatter = extract_frontmatter(text)
+    if frontmatter is None:
+        issues.append(Issue("error", "missing_frontmatter", "Rule is missing YAML frontmatter (--- block)"))
+    else:
+        # type field
+        rule_type = extract_frontmatter_field(frontmatter, TYPE_PATTERN)
+        if rule_type is None:
+            issues.append(Issue("error", "missing_type", "Frontmatter missing 'type' field (must be 'always', 'auto', or 'manual')"))
+        elif rule_type not in VALID_RULE_TYPES:
+            issues.append(Issue("error", "invalid_type", f"Invalid type '{rule_type}'; must be 'always', 'auto', or 'manual'"))
+
+        # source field — optional (schema default `package` injected at read);
+        # validate the value only when present.
+        rule_source = extract_frontmatter_field(frontmatter, SOURCE_PATTERN)
+        if rule_source is not None and rule_source not in VALID_RULE_SOURCES:
+            issues.append(Issue("error", "invalid_source", f"Invalid source '{rule_source}'; must be 'package' or 'project'"))
+
+        # description required for auto rules
+        if rule_type == "auto":
+            description = extract_description(text)
+            if not description:
+                issues.append(Issue("error", "auto_missing_description", "Auto rules require a 'description' field for matching"))
+
+        # description length cap (F6 — 200-char hard cap, see road-to-governance-cleanup)
+        rule_description = extract_description(text)
+        if rule_description and len(rule_description) > 200:
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(rule_description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
+
+        # always-rules that look like auto candidates (rule-type-governance check)
+        if rule_type == "always":
+            description = extract_description(text) or ""
+            # If description contains topic-specific keywords, it might be an auto candidate
+            topic_keywords = re.findall(
+                r"\b(?:PHP|Laravel|Docker|Git|E2E|Playwright|SQL|Blade|Livewire|"
+                r"Terraform|Jira|Sentry|translations|i18n)\b",
+                description, re.IGNORECASE)
+            if len(topic_keywords) >= 2:
+                issues.append(Issue("info", "always_auto_candidate",
+                                    f"Always-rule with topic-specific description ({', '.join(topic_keywords)}) — "
+                                    f"consider auto type per rule-type-governance"))
+
+        # Router schema validation (docs/contracts/rule-router.md, Phase 3.3).
+        issues.extend(lint_router_frontmatter(path.stem, frontmatter, rule_type))
+
+    # --- Structure checks ---
+    # H1 heading
+    if not H1_PATTERN.search(text):
+        issues.append(Issue("error", "missing_h1", "Rule is missing an H1 heading (# Title)"))
+
+    # File must end with exactly one newline
+    if not text.endswith("\n"):
+        issues.append(Issue("error", "no_trailing_newline", "File must end with exactly one newline"))
+    elif text.endswith("\n\n"):
+        issues.append(Issue("warning", "extra_trailing_newlines", "File ends with multiple newlines; should be exactly one"))
+
+    # No double/triple blank lines in content
+    if DOUBLE_BLANK_PATTERN.search(text):
+        issues.append(Issue("warning", "double_blank_lines", "File contains double or triple blank lines"))
+
+    # --- Content checks (docs/contracts/linter-structural-model.md) ---
+    # Structural-density gate replaces fenced-ratio + dual-threshold (Phase 3
+    # of road-to-structural-linter-reform, 2026-05-08): warn only when the
+    # rule is long, prose-dominant, AND ships no Iron-Law block. Hard error
+    # at 200 lines stays unconditional.
+    line_count = len([line for line in text.splitlines() if line.strip()])
+    total_lines = len(text.splitlines())
+    if total_lines > 200:
+        issues.append(Issue("error", "rule_too_large", f"Rule has {total_lines} lines (hard limit: 200); must split or move to guideline"))
+    elif line_count > 60:
+        density = _density_score(text)
+        iron_blocks = _iron_law_blocks(text)
+        if density < 0.5 and iron_blocks == 0:
+            issues.append(Issue(
+                "warning",
+                "long_rule",
+                f"Rule has {line_count} non-empty lines, density {density:.2f} < 0.50, "
+                f"no Iron-Law block; rules should be concise "
+                f"(see linter-structural-model contract)",
+            ))
+
+    for bad_sign in RULE_BAD_SIGNS:
+        if bad_sign in text:
+            issues.append(Issue("error", "rule_looks_like_skill", f"Rule contains skill-like section: {bad_sign}"))
+
+    # Procedural-rule heuristic: a rule "looks procedural" only when its own
+    # prose AND its own structure both signal a procedure. We:
+    #   1. Exclude frontmatter (may contain "type", path strings, etc.).
+    #   2. Strip code spans, fenced blocks, and markdown links — so legitimate
+    #      pointers to procedural skills (e.g. `skill:git-workflow`,
+    #      [symfony-workflow](…)) do not flip the keyword count.
+    #   3. Require ≥ 2 keyword occurrences in stripped prose AND ≥ 3 ordered
+    #      steps AND no Iron-Law block — that combination distinguishes a
+    #      mis-classified procedure from a rule that merely references one.
+    body = text.split("---", 2)[-1] if frontmatter else text
+    stripped_body = _strip_markdown_for_check(body)
+    kw_count = len(re.findall(r"\b(procedure|workflow)\b", stripped_body, re.IGNORECASE))
+    ordered_steps = len(re.findall(r"^\s*\d+\.\s+", body, re.MULTILINE))
+    if kw_count >= 2 and ordered_steps >= 3 and _iron_law_blocks(text) == 0:
+        issues.append(Issue("warning", "procedural_rule", "Rule looks procedural; consider a skill instead"))
+
+    return LintResult(
+        file=str(path),
+        artifact_type="rule",
+        status=classify_status(issues),
+        issues=issues,
+        suggestions=dedupe_preserve_order(suggestions),
+    )
+
+
+def _lint_command_suggestion_block(text: str) -> List[Issue]:
+    """Validate the suggestion frontmatter block (road-to-context-aware-command-suggestion).
+
+    Schema-shape is enforced upstream by validate_frontmatter; this function adds the
+    *conditional* content rules that JSON Schema (Draft-07 subset used here) cannot
+    express: trigger fields must be non-empty when eligible, rationale must be
+    non-empty when ineligible.
+    """
+    issues: List[Issue] = []
+    data, _offset = parse_frontmatter_for_schema(text)
+    if data is None:
+        return issues
+    suggestion = data.get("suggestion")
+    if suggestion is None:
+        issues.append(Issue(
+            "error", "missing_suggestion_block",
+            "Command frontmatter is missing the 'suggestion' block — required by "
+            "road-to-context-aware-command-suggestion Phase 2.",
+        ))
+        return issues
+    if not isinstance(suggestion, dict):
+        issues.append(Issue("error", "invalid_suggestion_block", "'suggestion' must be a mapping"))
+        return issues
+    eligible = suggestion.get("eligible")
+    if eligible is True:
+        td = (suggestion.get("trigger_description") or "").strip()
+        tc = (suggestion.get("trigger_context") or "").strip()
+        if not td:
+            issues.append(Issue(
+                "error", "missing_trigger_description",
+                "suggestion.eligible=true requires a non-empty 'trigger_description'.",
+            ))
+        elif len(td) < 10:
+            issues.append(Issue(
+                "warning", "trigger_description_too_short",
+                "suggestion.trigger_description is suspiciously short (<10 chars); "
+                "linter rejects empty or overly generic patterns.",
+            ))
+        if not tc:
+            issues.append(Issue(
+                "error", "missing_trigger_context",
+                "suggestion.eligible=true requires a non-empty 'trigger_context'.",
+            ))
+        elif len(tc) < 10:
+            issues.append(Issue(
+                "warning", "trigger_context_too_short",
+                "suggestion.trigger_context is suspiciously short (<10 chars); "
+                "linter rejects empty or overly generic patterns.",
+            ))
+    elif eligible is False:
+        rationale = (suggestion.get("rationale") or "").strip()
+        if not rationale:
+            issues.append(Issue(
+                "error", "missing_suggestion_rationale",
+                "suggestion.eligible=false requires a non-empty 'rationale'.",
+            ))
+    else:
+        issues.append(Issue(
+            "error", "invalid_suggestion_eligible",
+            "suggestion.eligible must be true or false.",
+        ))
+    return issues
+
+
+def lint_command(path: Path, text: str) -> LintResult:
+    issues: List[Issue] = []
+    suggestions: List[str] = []
+
+    # --- Frontmatter checks ---
+    frontmatter = extract_frontmatter(text)
+    if frontmatter is None:
+        issues.append(Issue("error", "missing_frontmatter", "Command is missing YAML frontmatter (--- block)"))
+    else:
+        # name field
+        name_match = NAME_PATTERN.search(frontmatter)
+        if not name_match or not name_match.group(1).strip():
+            issues.append(Issue("error", "missing_name", "Frontmatter missing 'name' field"))
+
+        # disable-model-invocation field — optional (schema default `true`
+        # injected at read); validate the value only when present.
+        dmi_match = DISABLE_MODEL_PATTERN.search(frontmatter)
+        if dmi_match and dmi_match.group(1) != "true":
+            issues.append(Issue("warning", "disable_model_invocation_false",
+                                "disable-model-invocation should be 'true' for commands"))
+
+        # description field
+        description = extract_description(text)
+        if not description:
+            issues.append(Issue("warning", "missing_description", "Frontmatter description is missing"))
+        elif len(description) > 200:
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
+
+        # suggestion block (road-to-context-aware-command-suggestion Phase 2)
+        issues.extend(_lint_command_suggestion_block(text))
+
+        # deprecation-shim warning line (P0.8b — command-clusters contract)
+        if "superseded_by:" in frontmatter:
+            shim_warning = re.search(
+                r"⚠️\s+/[a-z][a-z0-9-]*\s+is deprecated;\s+use\s+/[a-z][a-z0-9 -]+\s+instead",
+                text,
+            )
+            if not shim_warning:
+                issues.append(Issue(
+                    "error", "shim_missing_warning",
+                    "Deprecation shim must contain a one-line warning matching "
+                    "'⚠️  /<old-name> is deprecated; use /<cluster> <sub> instead.'"
+                    " (or '/<cluster> --<flag>' for flag-clusters)"
+                    " (see docs/contracts/command-clusters.md § Deprecation shim contract)"
+                ))
+
+    # --- Structure checks ---
+    if not H1_PATTERN.search(text):
+        issues.append(Issue("error", "missing_h1", "Command is missing an H1 heading (# Title)"))
+
+    # Must have at least one ## section with steps. Cluster-head and
+    # router-style commands (frontmatter cluster:/routes_to: or ≥ 3 .md
+    # links) are exempt — they delegate procedure to sub-commands or
+    # skills (road-to-feedback-followups P2.1).
+    sections = extract_sections(text)
+    has_steps = any(s.lower().startswith("step") for s in sections)
+    # Accept both ``## 1.`` / ``### 1.`` numbered headings AND
+    # ``### Step N`` / ``## Step N`` step-prefixed sub-headings.
+    has_numbered = bool(re.search(r"^###?\s+(?:\d+\.|step\s+\d+)\s+", text, re.MULTILINE | re.IGNORECASE))
+    if not has_steps and not has_numbered:
+        delegated = _command_delegation_signal(text, frontmatter)
+        if not delegated:
+            issues.append(Issue("warning", "no_steps", "Command has no Steps section or numbered sub-headings"))
+
+    # --- Size check (docs/contracts/linter-structural-model.md) ---
+    # Structural-density gate replaces sub-section + code-block heuristic
+    # (Phase 3 of road-to-structural-linter-reform, 2026-05-08): warn only
+    # when the command is large, lacks a delegation signal (frontmatter
+    # cluster:/routes_to: OR ≥ 3 markdown links to other .md files), AND
+    # has density < 0.65.
+    word_count = len(text.split())
+    if word_count > 1000:
+        density = _density_score(text)
+        delegated = _command_delegation_signal(text, frontmatter)
+        if not delegated and density < 0.65:
+            issues.append(Issue(
+                "warning",
+                "large_command",
+                f"Command has {word_count} words, density {density:.2f} < 0.65, "
+                f"no delegation signal (frontmatter cluster:/routes_to: or "
+                f"≥ 3 .md links); review for split or delegation "
+                f"(see linter-structural-model contract)",
+            ))
+
+    # File must end with exactly one newline
+    if not text.endswith("\n"):
+        issues.append(Issue("error", "no_trailing_newline", "File must end with exactly one newline"))
+    elif text.endswith("\n\n"):
+        issues.append(Issue("warning", "extra_trailing_newlines", "File ends with multiple newlines; should be exactly one"))
+
+    # Role-contract anchor validity (road-to-role-modes Phase 1).
+    issues.extend(lint_role_contract_refs(text))
+
+    return LintResult(
+        file=str(path),
+        artifact_type="command",
+        status=classify_status(issues),
+        issues=issues,
+        suggestions=dedupe_preserve_order(suggestions),
+    )
+
+
+def lint_unknown(path: Path, text: str) -> LintResult:
+    issues = [Issue("error", "unknown_artifact", "Could not detect whether file is a skill, rule, or command")]
+    return LintResult(
+        file=str(path),
+        artifact_type="unknown",
+        status="fail",
+        issues=issues,
+        suggestions=["Move the file into a recognized skills/, rules/, or commands/ path"],
+    )
+
+
+def lint_guideline(path: Path, text: str) -> LintResult:
+    """Lint a guideline .md file (size + structure checks)."""
+    issues: List[Issue] = []
+
+    # H1 heading
+    if not H1_PATTERN.search(text):
+        issues.append(Issue("warning", "missing_h1", "Guideline is missing an H1 heading"))
+
+    # Size check (guidelines/agent-infra/size-and-scope.md: target 400-1500 words)
+    word_count = len(text.split())
+    if word_count > 1500:
+        issues.append(Issue("info", "large_guideline", f"Guideline has {word_count} words (target: 400-1500)"))
+
+    # Trailing newline
+    if not text.endswith("\n"):
+        issues.append(Issue("warning", "no_trailing_newline", "File must end with exactly one newline"))
+
+    return LintResult(
+        file=str(path),
+        artifact_type="guideline",
+        status=classify_status(issues),
+        issues=issues,
+        suggestions=[],
+    )
+
+
+def lint_persona(path: Path, text: str) -> LintResult:
+    """Lint a persona .md file (frontmatter schema + required sections + size)."""
+    issues: List[Issue] = []
+
+    # Frontmatter required
+    frontmatter = extract_frontmatter(text)
+    if not frontmatter:
+        issues.append(Issue("error", "missing_frontmatter", "Persona requires YAML frontmatter"))
+        return LintResult(
+            file=str(path),
+            artifact_type="persona",
+            status="fail",
+            issues=issues,
+            suggestions=["See .agent-src.uncondensed/templates/persona.md for the schema"],
+        )
+
+    # Required frontmatter fields
+    required = {
+        "id": re.compile(r'^id:\s*"?([\w-]+)"?\s*$', re.MULTILINE),
+        "role": re.compile(r'^role:\s*"?(.+?)"?\s*$', re.MULTILINE),
+        "description": re.compile(r'^description:\s*"?(.+?)"?\s*$', re.MULTILINE),
+        "tier": re.compile(r'^tier:\s*"?(\w+)"?\s*$', re.MULTILINE),
+    }
+    # `version` (default "1.0") and `source` (default "package") carry schema
+    # defaults — they are injected at read time, so omitting them is valid.
+    # Validate the value only when present; never require presence.
+    optional_defaulted = {
+        "version": re.compile(r'^version:\s*"?(.+?)"?\s*$', re.MULTILINE),
+        "source": re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE),
+    }
+    parsed: dict = {}
+    for field, pattern in required.items():
+        value = extract_frontmatter_field(frontmatter, pattern)
+        if not value:
+            issues.append(Issue("error", f"missing_{field}", f"Persona frontmatter must declare `{field}`"))
+        else:
+            parsed[field] = value
+    for field, pattern in optional_defaulted.items():
+        value = extract_frontmatter_field(frontmatter, pattern)
+        if value:
+            parsed[field] = value
+
+    # id matches filename stem
+    if "id" in parsed and parsed["id"] != path.stem:
+        issues.append(Issue(
+            "error",
+            "id_filename_mismatch",
+            f"Persona id `{parsed['id']}` must match filename stem `{path.stem}`",
+        ))
+
+    # tier in valid set
+    if "tier" in parsed and parsed["tier"] not in VALID_PERSONA_TIERS:
+        issues.append(Issue(
+            "error",
+            "invalid_tier",
+            f"Persona tier `{parsed['tier']}` must be one of {sorted(VALID_PERSONA_TIERS)}",
+        ))
+
+    # wing — optional; when present must be one of {1,2,3,4} (per
+    # docs/contracts/package-self-orientation.md § The four wings).
+    wing_match = re.search(r'^wing:\s*"?(\d+)"?\s*$', frontmatter, re.MULTILINE)
+    if wing_match:
+        try:
+            wing_value = int(wing_match.group(1))
+            if wing_value in VALID_PERSONA_WINGS:
+                parsed["wing"] = wing_value
+            else:
+                issues.append(Issue(
+                    "error",
+                    "invalid_wing",
+                    f"Persona wing `{wing_value}` must be one of {sorted(VALID_PERSONA_WINGS)}",
+                ))
+        except ValueError:
+            issues.append(Issue(
+                "error",
+                "invalid_wing",
+                f"Persona wing `{wing_match.group(1)}` must be an integer 1–4",
+            ))
+
+    # description length
+    if "description" in parsed and len(parsed["description"]) > 160:
+        issues.append(Issue(
+            "warning",
+            "long_description",
+            f"Persona description is {len(parsed['description'])} chars (target ≤ 160)",
+        ))
+
+    # Required sections — tier-aware (per docs/contracts/persona-schema.md § 3).
+    # Core: 5 sections. Specialist: Core-5 + Critical Rules + Workflows.
+    sections = extract_sections(text)
+    tier = parsed.get("tier")
+    if tier == "specialist":
+        required_sections = REQUIRED_PERSONA_SECTIONS_SPECIALIST
+    else:
+        # Default to core sections when tier is missing or invalid; the
+        # tier-enum check above already raised an error in that case.
+        required_sections = REQUIRED_PERSONA_SECTIONS_CORE
+    for required_section in required_sections:
+        if required_section not in sections:
+            issues.append(Issue(
+                "error",
+                "missing_section",
+                f"Persona is missing required section `## {required_section}`",
+            ))
+
+    # Unique Questions must have ≥ 3 bullet items
+    uq_block = extract_section_block(text, "Unique Questions")
+    if uq_block:
+        bullet_count = len(re.findall(r"^\s*[-*]\s+", uq_block, re.MULTILINE))
+        if bullet_count < 3:
+            issues.append(Issue(
+                "warning",
+                "too_few_unique_questions",
+                f"Persona has {bullet_count} unique questions (target ≥ 3)",
+            ))
+
+    # Size budget by tier — wing-overrides apply when the persona declares a
+    # `wing:` field; defaults to the tier baseline otherwise.
+    if "tier" in parsed and parsed["tier"] in PERSONA_LINE_BUDGETS:
+        tier_value = parsed["tier"]
+        wing_value = parsed.get("wing")
+        budget = PERSONA_LINE_BUDGETS_BY_WING.get(
+            (tier_value, wing_value), PERSONA_LINE_BUDGETS[tier_value]
+        )
+        line_count = len(text.splitlines())
+        if line_count > budget:
+            scope = f"{tier_value}" if wing_value is None else f"{tier_value}, wing {wing_value}"
+            issues.append(Issue(
+                "warning",
+                "size_budget",
+                f"Persona has {line_count} lines ({scope} budget ≤ {budget})",
+            ))
+
+    # H1 heading
+    if not H1_PATTERN.search(text):
+        issues.append(Issue("warning", "missing_h1", "Persona is missing an H1 heading"))
+
+    # Trailing newline
+    if not text.endswith("\n"):
+        issues.append(Issue("warning", "no_trailing_newline", "File must end with exactly one newline"))
+
+    return LintResult(
+        file=str(path),
+        artifact_type="persona",
+        status=classify_status(issues),
+        issues=issues,
+        suggestions=[],
+    )
+
+
+def lint_usertype(path: Path, text: str) -> LintResult:
+    """Lint a user-type .md file (frontmatter schema + required sections + size).
+
+    User-types are the runtime end-user simulation lens (sister axis to
+    personas — methodology vs end-user). Contract:
+    docs/contracts/user-type-schema.md.
+    """
+    issues: List[Issue] = []
+
+    frontmatter = extract_frontmatter(text)
+    if not frontmatter:
+        issues.append(Issue("error", "missing_frontmatter", "User-type requires YAML frontmatter"))
+        return LintResult(
+            file=str(path),
+            artifact_type="user-type",
+            status="fail",
+            issues=issues,
+            suggestions=[".agent-src.uncondensed/user-types/_template/user-type.md"],
+        )
+
+    # Required keys per docs/contracts/user-type-schema.md § 1.
+    required = {
+        "id": re.compile(r'^id:\s*"?([\w-]+)"?\s*$', re.MULTILINE),
+        "kind": re.compile(r'^kind:\s*"?([\w-]+)"?\s*$', re.MULTILINE),
+        "description": re.compile(r'^description:\s*"?([^"\n]+?)"?\s*$', re.MULTILINE),
+        "version": re.compile(r'^version:\s*"?([\d.]+)"?\s*$', re.MULTILINE),
+        "source": re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE),
+    }
+    parsed: dict = {}
+    for field, pattern in required.items():
+        value = extract_frontmatter_field(frontmatter, pattern)
+        if not value:
+            issues.append(Issue("error", f"missing_{field}", f"User-type frontmatter must declare `{field}`"))
+        else:
+            parsed[field] = value
+
+    if "id" in parsed and parsed["id"] != path.stem:
+        issues.append(Issue(
+            "error",
+            "id_filename_mismatch",
+            f"User-type id `{parsed['id']}` must match filename stem `{path.stem}`",
+        ))
+
+    if "kind" in parsed and parsed["kind"] != "user-type":
+        issues.append(Issue(
+            "error",
+            "invalid_kind",
+            f"User-type kind must be `user-type` (got `{parsed['kind']}`)",
+        ))
+
+    if "description" in parsed and len(parsed["description"]) > 160:
+        issues.append(Issue(
+            "warning",
+            "long_description",
+            f"User-type description is {len(parsed['description'])} chars (target ≤ 160)",
+        ))
+
+    sections = extract_sections(text)
+    for required_section in REQUIRED_USERTYPE_SECTIONS:
+        if required_section not in sections:
+            issues.append(Issue(
+                "error",
+                "missing_section",
+                f"User-type is missing required section `## {required_section}`",
+            ))
+
+    # Anti-Generic Quality Bar: ≥ 3 Unique Questions
+    uq_block = extract_section_block(text, "Unique Questions")
+    if uq_block:
+        bullet_count = len(re.findall(r"^\s*[-*]\s+", uq_block, re.MULTILINE))
+        if bullet_count < 3:
+            issues.append(Issue(
+                "warning",
+                "too_few_unique_questions",
+                f"User-type has {bullet_count} unique questions (target ≥ 3)",
+            ))
+
+    line_count = len(text.splitlines())
+    if line_count > USERTYPE_LINE_BUDGET:
+        issues.append(Issue(
+            "warning",
+            "size_budget",
+            f"User-type has {line_count} lines (budget ≤ {USERTYPE_LINE_BUDGET})",
+        ))
+
+    if not H1_PATTERN.search(text):
+        issues.append(Issue("warning", "missing_h1", "User-type is missing an H1 heading"))
+
+    if not text.endswith("\n"):
+        issues.append(Issue("warning", "no_trailing_newline", "File must end with exactly one newline"))
+
+    return LintResult(
+        file=str(path),
+        artifact_type="user-type",
+        status=classify_status(issues),
+        issues=issues,
+        suggestions=[],
+    )
+
+
+def gather_all_candidate_files(root: Path) -> list[Path]:
+    """Gather all lintable files across every source root (ADR-017 multi-root).
+
+    Walks ``artefact_roots()`` (legacy ``.agent-src.uncondensed/`` plus every
+    ``packages/*/.agent-src.uncondensed/``). Falls back to ``dist/agent-src/``
+    only when no source root exists. Skips symlinks to avoid double-counting.
+    Deduplicates on logical relpath \u2014 first root wins per the agent_src
+    contract.
+    """
+    candidates: list[Path] = []
+    seen_logical: set[str] = set()
+
+    def _add(file: Path, source_root: Path) -> None:
+        if file.is_symlink() or not file.is_file():
+            return
+        try:
+            logical = file.relative_to(source_root).as_posix()
+        except ValueError:
+            logical = file.name
+        # Namespace by artefact-kind subdir so the same skill name across
+        # packs would still dedupe (but the agent_src layout guarantees
+        # each logical path lives in exactly one root post-move).
+        if logical in seen_logical:
+            return
+        seen_logical.add(logical)
+        candidates.append(file)
+
+    sources = artefact_roots()
+    if sources:
+        for src_root in sources:
+            for f in (src_root / "skills").rglob("SKILL.md") if (src_root / "skills").exists() else []:
+                _add(f, src_root)
+            for sub in ("rules", "commands", "guidelines"):
+                base = src_root / sub
+                if base.exists():
+                    for f in base.rglob("*.md"):
+                        _add(f, src_root)
+            for sub in ("personas", "user-types"):
+                base = src_root / sub
+                if base.exists():
+                    for f in base.glob("*.md"):
+                        if f.name.lower() == "readme.md":
+                            continue
+                        _add(f, src_root)
+            charter = src_root / FRUGALITY_CHARTER_RELPATH
+            if charter.exists() and not charter.is_symlink():
+                _add(charter, src_root)
+    else:
+        # Pure-condensed fallback (dist/agent-src/ only). Used by consumer
+        # projects that vendor the condensed tree without sources.
+        augment_root = root / "dist/agent-src"
+        if augment_root.exists():
+            for sub_pattern in (
+                ("skills", "SKILL.md"),
+                ("rules", "*.md"),
+                ("commands", "*.md"),
+                ("guidelines", "*.md"),
+            ):
+                base = augment_root / sub_pattern[0]
+                if base.exists():
+                    for f in base.rglob(sub_pattern[1]):
+                        _add(f, augment_root)
+            for sub in ("personas", "user-types"):
+                base = augment_root / sub
+                if base.exists():
+                    for f in base.glob("*.md"):
+                        if f.name.lower() == "readme.md":
+                            continue
+                        _add(f, augment_root)
+            charter = augment_root / FRUGALITY_CHARTER_RELPATH
+            if charter.exists() and not charter.is_symlink():
+                _add(charter, augment_root)
+
+    return sorted(set(candidates))
+
+
+def gather_candidate_files_under(src_root: Path) -> list[Path]:
+    """Gather lintable files under an arbitrary source root.
+
+    Mirrors the per-root walk used by ``gather_all_candidate_files`` but
+    scoped to a single directory \u2014 e.g. ``packages/pack-laravel/.agent-src.uncondensed/``
+    so CI can lint a single pack in parallel (ADR-017 Phase 4.4).
+    Skips symlinks and ``README.md`` siblings under ``personas/`` /
+    ``user-types/``.
+    """
+    out: list[Path] = []
+    if not src_root.is_dir():
+        return out
+    seen: set[Path] = set()
+
+    def _push(file: Path) -> None:
+        if file.is_symlink() or not file.is_file():
+            return
+        resolved = file.resolve()
+        if resolved in seen:
+            return
+        seen.add(resolved)
+        out.append(file)
+
+    skills_dir = src_root / "skills"
+    if skills_dir.exists():
+        for f in skills_dir.rglob("SKILL.md"):
+            _push(f)
+    for sub in ("rules", "commands", "guidelines"):
+        base = src_root / sub
+        if base.exists():
+            for f in base.rglob("*.md"):
+                _push(f)
+    for sub in ("personas", "user-types"):
+        base = src_root / sub
+        if base.exists():
+            for f in base.glob("*.md"):
+                if f.name.lower() == "readme.md":
+                    continue
+                _push(f)
+    charter = src_root / FRUGALITY_CHARTER_RELPATH
+    if charter.exists() and not charter.is_symlink():
+        _push(charter)
+    return sorted(set(out))
+
+
+def gather_changed_candidate_files(root: Path) -> list[Path]:
+    """Find changed skill/rule files using git diff.
+
+    Tries multiple strategies:
+    1. CI: diff against origin/main (PR changes)
+    2. Local: staged changes (git diff --cached)
+    3. Fallback: unstaged changes (git diff HEAD)
+    """
+    diff_commands = [
+        ["git", "diff", "--name-only", "origin/main...HEAD"],
+        ["git", "diff", "--name-only", "--cached", "HEAD"],
+        ["git", "diff", "--name-only", "HEAD"],
+    ]
+    try:
+        raw_lines: list[str] = []
+        for cmd in diff_commands:
+            result = subprocess.run(
+                cmd, cwd=root, text=True, capture_output=True, check=False,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                raw_lines = result.stdout.splitlines()
+                break
+
+        files = []
+        for raw in raw_lines:
+            raw = raw.strip()
+            if not raw:
+                continue
+            path = root / raw
+            if not path.exists():
+                continue
+            # Skip symlinks to avoid double-counting (e.g. .claude/skills/ → dist/agent-src/commands/)
+            if path.is_symlink():
+                continue
+            norm = raw.replace("\\", "/")
+            # Only lint source-of-truth and source-mirror dirs. Projection
+            # dirs (.windsurf/, .cursor/, .clinerules/, .claude/) use
+            # tool-native frontmatter (e.g. Windsurf's trigger/globs) that
+            # the linter does not validate — they regenerate from source.
+            # ADR-017: accept legacy flat layout AND
+            # packages/*/.agent-src.uncondensed/ paths.
+            in_source = (
+                norm.startswith(".agent-src.uncondensed/")
+                or norm.startswith("dist/agent-src/")
+                or "/.agent-src.uncondensed/" in norm
+                or "/dist/agent-src/" in norm
+            )
+            if not in_source:
+                continue
+            # Only .md artefacts are lintable. Skip data sidecars under
+            # `evals/` (e.g. commands/evals/<stem>.json routing evals, 6.0.0-C)
+            # — they are not commands/rules and have no frontmatter/H1.
+            is_md = path.suffix == ".md"
+            in_evals = "/evals/" in norm
+            if not in_evals and (
+                path.name == "SKILL.md"
+                or (is_md and ("/rules/" in norm or "/commands/" in norm))
+            ):
+                files.append(path)
+        return sorted(set(files))
+    except Exception:
+        return []
+
+
+# --- Interaction quality checks (keyword-based, for meta/interaction artifacts only) ---
+
+# File name patterns that indicate an interaction/meta artifact (strict — avoids false positives)
+_INTERACTION_NAME_PATTERNS = re.compile(
+    r"skill-router|handoff|analysis-skill|skill-writing|skill-reviewer|"
+    r"model-recommendation|developer-like-execution|universal-project-analysis|"
+    r"interaction|autonomous-mode|feature-planning",
+    re.IGNORECASE,
+)
+_INTERACTION_CONTENT_KEYWORDS = {"handoff", "model switch", "clarification", "ask the user", "framework choice", "requirements are unclear"}
+
+
+def _is_interaction_artifact(path: Path, text: str) -> bool:
+    """Check if file is an interaction/meta artifact that should get question-quality checks."""
+    name = str(path).lower()
+    # Strict name match — only truly interaction-focused artifacts
+    if _INTERACTION_NAME_PATTERNS.search(name):
+        return True
+    # Content match needs 3+ keywords to avoid false positives on analysis/coding skills
+    text_lower = text.lower()
+    matches = sum(1 for kw in _INTERACTION_CONTENT_KEYWORDS if kw in text_lower)
+    return matches >= 3
+
+
+def lint_interaction_quality(path: Path, text: str) -> List[Issue]:
+    """Check interaction/meta artifacts for question strategy, handoff order, etc."""
+    if not _is_interaction_artifact(path, text):
+        return []
+
+    issues: List[Issue] = []
+    text_lower = text.lower()
+
+    # Only check files that explicitly discuss user questioning strategy
+    has_question_context = any(kw in text_lower for kw in (
+        "ask the user", "ask clarification", "numbered options", "present options",
+        "question strategy", "ask before",
+    ))
+
+    # Check 1: Question strategy — distinguishes simple grouped vs complex sequential
+    if has_question_context:
+        has_simple = any(kw in text_lower for kw in ("simple", "binary", "independent"))
+        has_complex = any(kw in text_lower for kw in ("complex", "one at a time", "one question"))
+        if not (has_simple and has_complex):
+            issues.append(Issue("warning", "question_strategy_missing",
+                                "Interaction guidance does not distinguish simple grouped questions "
+                                "from complex sequential questions"))
+
+    # Check 2: Handoff ordering — handoff/model-switch questions should come last
+    has_handoff = any(kw in text_lower for kw in ("handoff", "model switch", "model-switch"))
+    if has_handoff:
+        has_ordering = any(kw in text_lower for kw in (
+            "last", "after context", "after clarification", "after all",
+        ))
+        if not has_ordering:
+            issues.append(Issue("warning", "handoff_order_missing",
+                                "Handoff/model-switch guidance does not specify asking handoff "
+                                "questions AFTER context/domain questions"))
+
+    # Check 3: Framework choice guard — only when file explicitly discusses choosing between systems
+    has_impl = any(kw in text_lower for kw in ("implement", "component", "ui component", "ui framework"))
+    has_multi = any(kw in text_lower for kw in ("multiple frameworks", "multiple systems", "competing", "which framework"))
+    if has_impl and has_multi:
+        has_guard = any(kw in text_lower for kw in (
+            "ask which", "ask before", "do not implement blindly", "analyze what exists",
+            "do not pick", "clarif",
+        ))
+        if not has_guard:
+            issues.append(Issue("warning", "framework_choice_guard_missing",
+                                "Discusses implementation choices but does not require clarification "
+                                "when multiple frameworks/patterns exist"))
+
+    # Check 4: Clarification guard — only for files with explicit interaction/execution guidance
+    has_execution_guidance = any(kw in text_lower for kw in ("procedure", "workflow", "step 1", "### 1."))
+    if has_execution_guidance:
+        has_clarification = any(kw in text_lower for kw in (
+            "requirements are unclear", "ask clarification", "do not assume",
+            "clarification question", "missing instructions", "incomplete",
+        ))
+        if not has_clarification:
+            issues.append(Issue("info", "clarification_guard_missing",
+                                "Contains action guidance but no explicit clarification behavior "
+                                "for incomplete requirements"))
+
+    # Check 5: Feedback learning — meta/reviewer artifacts should support learning
+    is_meta = any(kw in str(path).lower() for kw in ("review", "improve", "learn", "audit", "optim"))
+    if is_meta:
+        has_learning = any(kw in text_lower for kw in (
+            "learning", "feedback", "frustration", "capture", "improve the system",
+            "rule / skill", "rule/skill",
+        ))
+        if not has_learning:
+            issues.append(Issue("info", "feedback_learning_missing",
+                                "Meta/reviewer artifact does not mention learning from negative "
+                                "feedback or converting failures into system improvements"))
+
+    return issues
+
+
+# --- Execution quality checks ---
+
+# File name signals for execution-oriented artifacts
+_EXEC_FILE_SIGNALS = (
+    "execution", "debug", "implement", "developer", "action",
+    "validation", "testing", "coder", "bug", "fix",
+)
+
+# Content signals that indicate execution-oriented artifact
+_EXEC_CONTENT_SIGNALS = (
+    "implement", "debug", "refactor", "modify", "fix",
+    "verify", "validate", "runtime", "test", "coding",
+    "before acting", "before coding", "before changing",
+)
+
+
+def _is_execution_artifact(path: Path, text: str) -> bool:
+    """Detect if artifact is execution/implementation oriented.
+
+    Only skills and rules qualify — commands and guidelines are excluded
+    because commands are workflows (not execution guidance) and guidelines
+    are coding patterns (not developer workflow enforcement).
+    """
+    path_lower = str(path).lower()
+    text_lower = text.lower()
+
+    # Exclude commands, guidelines, personas, user-types — not execution-oriented
+    if (
+        "/commands/" in path_lower
+        or "/guidelines/" in path_lower
+        or "/personas/" in path_lower
+        or "/user-types/" in path_lower
+    ):
+        return False
+
+    # File name match — strong signal
+    if any(sig in path_lower for sig in _EXEC_FILE_SIGNALS):
+        return True
+
+    # Content match — need at least 5 signals to avoid false positives
+    # (many artifacts mention "implement" or "fix" without being execution-focused)
+    matches = sum(1 for sig in _EXEC_CONTENT_SIGNALS if sig in text_lower)
+    return matches >= 5
+
+
+def lint_execution_quality(path: Path, text: str) -> List[Issue]:
+    """Check execution-oriented artifacts for developer workflow quality."""
+    if not _is_execution_artifact(path, text):
+        return []
+
+    issues: List[Issue] = []
+    text_lower = text.lower()
+    path_lower = str(path).lower()
+
+    # Strong match = file name signal; weak match = content-only signal
+    is_strong_match = any(sig in path_lower for sig in _EXEC_FILE_SIGNALS)
+
+    # --- Signal groups ---
+    # Each group uses broad synonyms to reduce false negatives.
+    # Skills often express analysis/verification concepts without using
+    # the exact words "analyze" or "verify".
+    analysis_signals = (
+        "analyze", "inspect", "understand", "read relevant",
+        "review existing", "trace flow", "read affected",
+        "check current", "before acting", "before coding",
+        # Synonyms added in Phase 2b
+        "examine", "study", "investigate", "check existing",
+        "gather context", "read project", "read the changelog",
+        "identify break", "assess", "before upgrading",
+        "before changing", "before creating", "before modifying",
+        "read docs", "read module", "read agents",
+    )
+
+    verification_signals = (
+        "verify", "validate", "test", "real execution",
+        "run endpoint", "playwright", "curl", "postman",
+        "debugger", "run tests", "hit the endpoint",
+        # Synonyms added in Phase 2b
+        "confirm", "assert", "check result", "observe",
+        "run phpstan", "run rector", "build and verify",
+        "must pass", "response shape",
+    )
+
+    verification_tool_signals = (
+        "playwright", "curl", "postman", "xdebug",
+        "browser", "http::fake",
+        # Synonyms added in Phase 2b
+        "phpstan", "rector", "phpunit", "pest",
+        "devcontainer build",
+    )
+
+    debug_runtime_signals = (
+        "debugger", "xdebug", "mcp debugger", "runtime inspection",
+        "trace execution", "breakpoint", "step through",
+        # Synonyms added in Phase 2b
+        "runtime", "stack trace", "dump", "dd(",
+    )
+
+    efficient_tooling_signals = (
+        "jq", " rg ", "grep", "filter", "selective",
+        "extract", "targeted", "--json", "--filter",
+        # Synonyms added in Phase 2b
+        "narrow", "scoped", "specific field", "only relevant",
+    )
+
+    anti_bruteforce_signals = (
+        "avoid retr", "do not brute", "do not guess",
+        "do not retry blind", "analyze before retry",
+        "blind retr", "trial-and-error", "trial and error",
+        "max 2 retries", "stop and rethink",
+        # Synonyms added in Phase 2b
+        "diagnose", "root cause", "targeted fix",
+        "do not blindly", "never guess",
+    )
+
+    clarification_signals = (
+        "ask", "clarif", "unclear", "missing information",
+        "do not assume", "don't assume", "instead of assuming",
+        # Synonyms added in Phase 2b
+        "confirm with user", "verify requirement", "ambiguous",
+        "if unsure", "when in doubt",
+    )
+
+    # Helper
+    def has_any(signals: tuple[str, ...]) -> bool:
+        return any(s in text_lower for s in signals)
+
+    # --- Section-based detection (complement to keyword matching) ---
+    # Detects structural signals: sections whose names imply analysis or verification.
+    import re
+    section_headers = re.findall(r'^#{1,4}\s+(.+)$', text, re.MULTILINE)
+    section_headers_lower = [h.lower() for h in section_headers]
+
+    # Section names that imply analysis-before-action
+    has_analysis_section = any(
+        any(kw in h for kw in ("understand", "analyze", "assess", "context", "review",
+                                "current setup", "current state", "before"))
+        for h in section_headers_lower
+    )
+
+    # Section names that imply verification
+    has_verification_section = any(
+        any(kw in h for kw in ("verify", "validat", "test", "acceptance", "quality gate"))
+        for h in section_headers_lower
+    )
+
+    # Section names that imply anti-patterns / gotchas
+    has_antipattern_section = any(
+        any(kw in h for kw in ("do not", "don't", "gotcha", "anti-pattern", "avoid"))
+        for h in section_headers_lower
+    )
+
+    # Detect implementation/change language
+    change_signals = ("implement", "modify", "fix", "refactor", "change", "update", "code")
+    has_change_language = any(s in text_lower for s in change_signals)
+
+    # Combine keyword + section signals
+    has_analysis = has_any(analysis_signals) or has_analysis_section
+    has_verification = has_any(verification_signals) or has_verification_section
+
+    # --- Check 1: Missing analysis-before-action (ERROR, skills only) ---
+    # Rules describe constraints, not workflows — they don't need analysis sections
+    is_skill = "/skills/" in str(path).lower()
+    if is_skill and has_change_language and not has_analysis:
+        issues.append(Issue("error", "missing_analysis_before_action",
+                            "Execution-oriented skill encourages implementation "
+                            "without requiring prior analysis of existing system"))
+
+    # --- Check 2: Missing real verification (ERROR, skills with strong match) ---
+    if is_skill and is_strong_match and has_change_language and not has_verification:
+        issues.append(Issue("error", "missing_real_verification",
+                            "Implementation/debugging skill does not require "
+                            "real verification after changes"))
+
+    # Checks 3-7 only apply to strong matches (file name signal) to avoid noise
+    # on generic skills that happen to mention "implement" or "fix"
+    if is_strong_match:
+        # --- Check 3: Missing verification tool mapping (WARNING) ---
+        if has_any(verification_signals) and not has_any(verification_tool_signals):
+            issues.append(Issue("warning", "missing_verification_tool_mapping",
+                                "Verification is generic — does not reference concrete "
+                                "tools (Playwright, curl, Postman, Xdebug)"))
+
+        # --- Check 4: Missing runtime debug guidance (WARNING) ---
+        debug_context = any(s in text_lower for s in ("debug", "execution flow", "trace", "unexpected behavior"))
+        if debug_context and not has_any(debug_runtime_signals):
+            issues.append(Issue("warning", "missing_runtime_debug_guidance",
+                                "Debugging/execution artifact does not mention "
+                                "runtime debug tools (Xdebug, debugger, breakpoints)"))
+
+        # --- Check 5: Missing efficient tooling guidance (WARNING) ---
+        data_context = any(s in text_lower for s in ("api", "log", "json", "response", "output", "data"))
+        if data_context and not has_any(efficient_tooling_signals):
+            issues.append(Issue("warning", "missing_efficient_tooling_guidance",
+                                "Artifact does not encourage targeted filtering tools "
+                                "(jq, rg, grep) for reducing output"))
+
+        # --- Check 6: Missing anti-bruteforce guidance (WARNING, skills only) ---
+        if is_skill and has_change_language and not has_any(anti_bruteforce_signals):
+            issues.append(Issue("warning", "missing_anti_bruteforce_guidance",
+                                "Execution guidance lacks explicit anti-retry / "
+                                "anti-bruteforce behavior"))
+
+        # --- Check 7: Missing clarification guard (WARNING, skills only) ---
+        if is_skill and has_change_language and not has_any(clarification_signals):
+            issues.append(Issue("warning", "missing_clarification_guard",
+                                "Implementation guidance does not require clarification "
+                                "when requirements are incomplete"))
+
+    return issues
+
+
+# --- Type boundary checks ---
+
+
+def lint_type_boundaries(path: Path, text: str, artifact_type: str) -> List[Issue]:
+    """Check that artifacts respect their type boundaries.
+
+    - Guidelines should not contain executable procedures
+    - Commands should reference skills
+    - Skills should have concrete validation (not vague)
+    """
+    issues: List[Issue] = []
+    text_lower = text.lower()
+    import re
+
+    # --- Guideline: should not have executable procedures ---
+    if artifact_type == "guideline":
+        # Count numbered steps (1. 2. 3. etc.) — guidelines shouldn't have >5
+        numbered_steps = re.findall(r'^\d+\.\s+\*?\*?(?:Step|Run|Create|Execute|Implement)',
+                                     text, re.MULTILINE | re.IGNORECASE)
+        if len(numbered_steps) >= 5:
+            issues.append(Issue("warning", "guideline_contains_executable_procedure",
+                                f"Guideline has {len(numbered_steps)} executable numbered steps — "
+                                "consider extracting into a skill or command"))
+
+    # --- Command: should reference skills ---
+    if artifact_type == "command":
+        # Check frontmatter skills field
+        frontmatter = extract_frontmatter(text)
+        has_skills_field = False
+        # Commands tagged `type: orchestrator` aggregate other commands /
+        # routers — they intentionally do not declare a `skills:` list and
+        # are exempt from the no-skill-reference check. The tag is the
+        # contract; no hard-coded path list.
+        is_orchestrator = False
+        if frontmatter:
+            skills_match = re.search(r'skills:\s*\[(.+)\]', frontmatter)
+            has_skills_field = bool(skills_match and skills_match.group(1).strip())
+            type_match = re.search(r'^type:\s*[\'"]?orchestrator[\'"]?\s*$',
+                                   frontmatter, re.MULTILINE)
+            is_orchestrator = bool(type_match)
+
+        # Also check body for skill references
+        has_skill_ref = bool(re.search(r'skill|SKILL\.md', text))
+
+        if not has_skills_field and not has_skill_ref and not is_orchestrator:
+            issues.append(Issue("warning", "command_missing_skill_references",
+                                "Command does not reference any skills — "
+                                "commands should orchestrate skills, not contain domain logic "
+                                "(use `type: orchestrator` in frontmatter to exempt routers)"))
+
+    # --- Skill: validation should be concrete, not vague ---
+    if artifact_type == "skill":
+        # Find validation/verify sections
+        validation_section = re.search(
+            r'(?:^#{1,4}\s+(?:Validat|Verif|Quality|Accept).+?\n)((?:.*\n)*?)(?=^#{1,4}\s|\Z)',
+            text, re.MULTILINE | re.IGNORECASE
+        )
+        if validation_section:
+            validation_text = validation_section.group(1).lower()
+            vague_patterns = ("check if it works", "make sure it's correct",
+                              "verify it works", "should work", "looks correct")
+            concrete_patterns = ("run ", "curl ", "phpstan", "rector", "pest",
+                                 "playwright", "assert", "exit code", "must pass",
+                                 "0 fail", "0 error")
+            has_vague = any(p in validation_text for p in vague_patterns)
+            has_concrete = any(p in validation_text for p in concrete_patterns)
+            if has_vague and not has_concrete:
+                issues.append(Issue("warning", "skill_validation_too_generic",
+                                    "Validation section uses vague language — "
+                                    "add concrete checks (commands, expected output, conditions)"))
+
+    return issues
+
+
+# --- Verification maturity checks ---
+
+# Task type detection signals
+_TASK_TYPE_SIGNALS = {
+    "backend": ("api", "endpoint", "controller", "route", "service", "repository",
+                "eloquent", "migration", "artisan", "middleware", "job", "queue"),
+    "frontend": ("blade", "livewire", "component", "view", "ui", "frontend",
+                 "tailwind", "flux", "css", "template"),
+    "cli": ("artisan command", "cli", "console", "schedule", "cron"),
+    "database": ("migration", "database", "schema", "index", "query", "sql",
+                 "mariadb", "mysql", "seeder"),
+    "debugging": ("debug", "xdebug", "error", "exception", "sentry", "trace",
+                  "breakpoint", "log"),
+}
+
+# Expected verification tools per task type
+_VERIFICATION_TOOLS = {
+    "backend": ("curl", "postman", "http::fake", "actingas", "api/"),
+    "frontend": ("playwright", "browser", "screenshot", "snapshot", "livewire test"),
+    "cli": ("exit code", "command output", "artisan test", "expectsoutput"),
+    "database": ("query", "assertdatabase", "migration", "seedandassert", "table"),
+    "debugging": ("xdebug", "breakpoint", "dump", "dd(", "stack trace", "log"),
+}
+
+
+def lint_verification_maturity(path: Path, text: str, artifact_type: str) -> List[Issue]:
+    """Check that verification matches the skill's task type."""
+    if artifact_type != "skill":
+        return []
+
+    # Only check skills with strong execution signals
+    path_lower = str(path).lower()
+    if not any(sig in path_lower for sig in _EXEC_FILE_SIGNALS):
+        return []
+
+    issues: List[Issue] = []
+    text_lower = text.lower()
+
+    # Detect task types present in the skill
+    detected_types: list[str] = []
+    for task_type, signals in _TASK_TYPE_SIGNALS.items():
+        matches = sum(1 for s in signals if s in text_lower)
+        if matches >= 2:  # Need at least 2 signals to classify
+            detected_types.append(task_type)
+
+    if not detected_types:
+        return []
+
+    # Check if appropriate verification tools are mentioned
+    for task_type in detected_types:
+        tools = _VERIFICATION_TOOLS.get(task_type, ())
+        has_tool = any(t in text_lower for t in tools)
+        if not has_tool:
+            issues.append(Issue("warning", f"missing_{task_type}_verification_example",
+                                f"Skill covers {task_type} tasks but does not mention "
+                                f"verification tools for that context "
+                                f"(e.g. {', '.join(tools[:3])})"))
+
+    return issues
+
+
+# --- Governance & packaging checks ---
+
+
+# --- Frugality validator helpers + Layers 1 & 2 ---
+
+def _heading_to_slug(heading: str) -> str:
+    """Slugify a markdown heading using GitHub's algorithm: lowercase,
+    drop punctuation (em-dash, period, etc.), spaces -> hyphens,
+    preserve adjacent hyphens (so `Iron Law 3 — Brevity` becomes
+    `iron-law-3--brevity`, matching the anchor GitHub renders)."""
+    s = heading.strip().lower()
+    s = re.sub(r"[^a-z0-9 \-]", "", s)
+    s = s.replace(" ", "-")
+    return s.strip("-")
+
+
+def _extract_heading_slugs(text: str) -> set[str]:
+    """Return the set of slugs for every H2/H3 heading in a markdown body."""
+    slugs: set[str] = set()
+    for line in text.splitlines():
+        if line.startswith("## ") or line.startswith("### "):
+            heading = line.split(" ", 1)[1].strip()
+            slugs.add(_heading_to_slug(heading))
+    return slugs
+
+
+def _skill_id_from_path(path: Path) -> Optional[str]:
+    """Extract the writer-skill id from a SKILL.md path. Returns the
+    parent-directory name, or None if the file is not a SKILL.md."""
+    if path.name.lower() != "skill.md":
+        return None
+    return path.parent.name
+
+
+def _is_frugality_charter(path: Path) -> bool:
+    """True iff the path ends in the canonical charter relpath, regardless
+    of whether it lives under dist/agent-src/ or .agent-src.uncondensed/."""
+    norm = str(path).replace("\\", "/")
+    return norm.endswith("/" + FRUGALITY_CHARTER_RELPATH)
+
+
+# Section header recognised by Layer 1. Literal H2 only — sub-headings
+# inside the section do not count as the section itself.
+_FRUGALITY_STANDARDS_PATTERN = re.compile(
+    r"^##\s+Frugality Standards\s*$", re.MULTILINE
+)
+_FRUGALITY_CHARTER_LINK_PATTERN = re.compile(
+    r"\]\([^)]*frugality-charter\.md[^)]*\)"
+)
+
+
+def lint_frugality_writer_cite(path: Path, text: str,
+                                artifact_type: str) -> List[Issue]:
+    """Layer 1 — every writer skill must carry a `## Frugality Standards`
+    section that links to the charter. No-op for non-writer skills and
+    non-skill artifacts."""
+    if artifact_type != "skill":
+        return []
+    skill_id = _skill_id_from_path(path)
+    if skill_id is None or skill_id not in FRUGALITY_WRITER_SKILLS:
+        return []
+    issues: List[Issue] = []
+    section_match = _FRUGALITY_STANDARDS_PATTERN.search(text)
+    if not section_match:
+        issues.append(Issue(
+            "error", "frugality_section_missing",
+            "Writer skill must carry a `## Frugality Standards` section "
+            "(road-to-token-frugality Phase 0.4 Layer 1)",
+        ))
+        return issues
+    # Section body = from match-end to next H2 or EOF.
+    body_start = section_match.end()
+    next_h2 = re.search(r"^##\s+", text[body_start:], re.MULTILINE)
+    body_end = body_start + next_h2.start() if next_h2 else len(text)
+    body = text[body_start:body_end]
+    if not _FRUGALITY_CHARTER_LINK_PATTERN.search(body):
+        issues.append(Issue(
+            "error", "frugality_charter_cite_missing",
+            "`## Frugality Standards` section must link to "
+            "`frugality-charter.md` (road-to-token-frugality Phase 0.4 "
+            "Layer 1)",
+        ))
+    return issues
+
+
+# Markdown link pattern: [text](path#anchor) — anchor optional.
+_MD_LINK_PATTERN = re.compile(
+    r"\[[^\]]+\]\(([^)#]+)(?:#([^)]+))?\)"
+)
+
+
+def lint_frugality_charter_index(path: Path, text: str) -> List[Issue]:
+    """Layer 2 — every cited anchor must resolve to a real H2/H3 heading
+    in the target rule file, AND each of the four canonical rules must
+    be cited at least once with the required canonical anchor substring.
+    Additional citations to the same rule (net-new sections referencing
+    other anchors) are validated for resolution but do not need the
+    canonical substring."""
+    if not _is_frugality_charter(path):
+        return []
+    issues: List[Issue] = []
+    rules_dir = path.parent.parent.parent / "rules"
+    rule_slugs_cache: dict[str, set[str]] = {}
+    canonical_satisfied: set[str] = set()
+    for link_match in _MD_LINK_PATTERN.finditer(text):
+        link_path, link_anchor = link_match.group(1), link_match.group(2)
+        rule_name = Path(link_path).name
+        if rule_name not in FRUGALITY_CHARTER_INDEX_RULES:
+            continue
+        if link_anchor is None:
+            continue
+        anchor_lc = link_anchor.lower()
+        required_substr = FRUGALITY_CHARTER_INDEX_RULES[rule_name]
+        if required_substr in anchor_lc:
+            canonical_satisfied.add(rule_name)
+        if rule_name not in rule_slugs_cache:
+            rule_file = rules_dir / rule_name
+            if not rule_file.exists():
+                issues.append(Issue(
+                    "error", "frugality_charter_rule_missing",
+                    f"Charter cites {rule_name} but the rule file does "
+                    f"not exist at {rule_file}",
+                ))
+                rule_slugs_cache[rule_name] = set()
+                continue
+            try:
+                rule_text = rule_file.read_text(encoding="utf-8")
+            except OSError as e:
+                issues.append(Issue(
+                    "error", "frugality_charter_rule_unreadable",
+                    f"Cannot read {rule_name}: {e}",
+                ))
+                rule_slugs_cache[rule_name] = set()
+                continue
+            rule_slugs_cache[rule_name] = _extract_heading_slugs(rule_text)
+        if anchor_lc not in rule_slugs_cache[rule_name]:
+            issues.append(Issue(
+                "error", "frugality_charter_anchor_unresolved",
+                f"Charter cites {rule_name}#{link_anchor} but no H2/H3 "
+                f"heading with that slug exists in the rule file",
+            ))
+    missing = set(FRUGALITY_CHARTER_INDEX_RULES) - canonical_satisfied
+    for rule_name in sorted(missing):
+        required_substr = FRUGALITY_CHARTER_INDEX_RULES[rule_name]
+        issues.append(Issue(
+            "error", "frugality_charter_canonical_missing",
+            f"Charter index lacks a canonical citation of {rule_name} "
+            f"with anchor containing '{required_substr}' "
+            f"(road-to-token-frugality Phase 0.4 Layer 2)",
+        ))
+    return issues
+
+
+def lint_governance(path: Path, text: str, artifact_type: str, repo_root: Path | None = None) -> List[Issue]:
+    """Check governance and packaging consistency.
+
+    - Condensed/uncondensed pairs must exist
+    - No duplicate skill names
+    - Files must be in correct location for their type
+    """
+    issues: List[Issue] = []
+    if repo_root is None:
+        return issues
+
+    path_str = str(path)
+    path_relative = path_str
+
+    # Determine if this is a condensed or uncondensed artifact
+    is_condensed = "/dist/agent-src/" in path_str and "/.agent-src.uncondensed/" not in path_str
+    is_uncondensed = "/.agent-src.uncondensed/" in path_str
+
+    if not is_condensed and not is_uncondensed:
+        return issues
+
+    # --- Check: condensed/uncondensed pair exists ---
+    # ADR-017: sources live under packages/*/.agent-src.uncondensed/ but
+    # all packs project into the single repo-root dist/agent-src/ tree. The
+    # pair-check now resolves via logical relpath, not a path-swap.
+    from _lib.agent_src import strip_source_prefix as _strip
+    norm = path_str.replace("\\", "/")
+    if is_uncondensed:
+        # Compute logical path then map to dist/agent-src/ at repo root.
+        # Try direct strip first; fall back to substring split for absolute paths.
+        logical = _strip(norm)
+        if logical is None:
+            marker = "/.agent-src.uncondensed/"
+            idx = norm.rfind(marker)
+            logical = norm[idx + len(marker):] if idx != -1 else None
+        if logical:
+            condensed_path = repo_root / "dist/agent-src" / logical
+            if not condensed_path.exists():
+                issues.append(Issue("warning", "condensed_variant_missing",
+                                    f"Uncondensed file exists but condensed variant missing: "
+                                    f"{condensed_path.name}"))
+    elif is_condensed:
+        # Condensed lives at repo-root dist/agent-src/<logical>. Source could
+        # be at any source root \u2014 resolve via artefact_roots.
+        marker = "/dist/agent-src/"
+        idx = norm.rfind(marker)
+        logical = norm[idx + len(marker):] if idx != -1 else None
+        if logical:
+            uncondensed_path = resolve_logical(logical)
+            if uncondensed_path is None or not uncondensed_path.exists():
+                issues.append(Issue("warning", "uncondensed_variant_missing",
+                                    f"Condensed file exists but uncondensed source missing: "
+                                    f"{Path(logical).name}"))
+
+    # --- Check: file in correct location for type ---
+    location_map = {
+        "skill": "/skills/",
+        "rule": "/rules/",
+        "command": "/commands/",
+        "guideline": "/guidelines/",
+    }
+    expected_loc = location_map.get(artifact_type)
+    if expected_loc and expected_loc not in path_str:
+        issues.append(Issue("warning", "invalid_location_for_type",
+                            f"Artifact detected as '{artifact_type}' but not in "
+                            f"expected location ({expected_loc})"))
+
+    return issues
+
+
+# --- Structural malice check (see road-to-suite-closure Phase 5) ---
+#
+# Five regex patterns scan skill / rule / command bodies for **structural**
+# (not semantic) malice. Findings surface as ``Issue("error",
+# "malice:<pattern>", "<line>:<matched>")`` so ``compute_exit_code`` can
+# emit exit code 3 (security-failure), distinct from 2 (build-failure).
+# Semantic checks (PII leakage, prompt injection) are deferred to v2.
+
+# (a) credential exfil — curl|wget piping ${TOKEN}/${KEY}/${SECRET}/...
+#     env vars or hitting ~/.aws/ ~/.ssh/ secrets.
+_MALICE_CRED_EXFIL = re.compile(
+    r"\b(?:curl|wget)\b[^\n]*"
+    r"(?:\$\{?[A-Z_]*(?:TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|API)[A-Z_]*\}?"
+    r"|~/\.(?:aws|ssh)/)"
+)
+# (b) arbitrary execution — eval/exec over a network-fetched payload, or
+#     `bash <(curl ...)` / `sh <(wget ...)` style remote-execution.
+_MALICE_REMOTE_EXEC = re.compile(
+    r"(?:\b(?:eval|exec)\s*\([^)]*(?:curl|wget|requests\.get|urllib)"
+    r"|\b(?:bash|sh|zsh)\s*<\s*\(\s*(?:curl|wget))"
+)
+# (c) force-push to a protected ref.
+_MALICE_FORCE_PUSH = re.compile(
+    r"\bgit\s+push\b[^\n]*--force(?:-with-lease)?\b[^\n]*"
+    r"\b(?:main|master|prod|production|release)\b"
+)
+# (d) world-readable secrets — chmod 0?[4567]xx on .pem/.key/.env files.
+_MALICE_CHMOD_SECRETS = re.compile(
+    r"\bchmod\s+0?[4567]\d{2}\s+[^\n]*\.(?:pem|key|env)\b"
+)
+# (e) unbounded subprocess shell injection — shell=True interpolating ${VAR}.
+_MALICE_SHELL_INJECT = re.compile(
+    r"\bsubprocess\.[A-Za-z_]+\s*\([^)]*shell\s*=\s*True[^)]*\$\{"
+)
+
+_MALICE_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("cred_exfil", _MALICE_CRED_EXFIL),
+    ("remote_exec", _MALICE_REMOTE_EXEC),
+    ("force_push_protected", _MALICE_FORCE_PUSH),
+    ("chmod_secrets", _MALICE_CHMOD_SECRETS),
+    ("shell_injection", _MALICE_SHELL_INJECT),
+]
+
+
+def check_structural_malice(text: str) -> List[Issue]:
+    """Return one Issue per malice match. Empty list when clean.
+
+    Issue shape: ``Issue("error", f"malice:{name}", f"{line}:{matched}")``.
+    The ``format_text`` renderer special-cases the ``malice:`` code prefix
+    to emit ``<path>:<line>:malice:<pattern>:<matched>`` per Phase 5.2.
+    """
+    issues: List[Issue] = []
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        for name, pattern in _MALICE_PATTERNS:
+            match = pattern.search(raw)
+            if match:
+                issues.append(Issue(
+                    severity="error",
+                    code=f"malice:{name}",
+                    message=f"{lineno}:{match.group(0).strip()}",
+                ))
+    return issues
+
+
+# --- Output-schema check (see road-to-trigger-evals Phase 3.5) ---
+#
+# Skills that freeze an output shape (`refine-ticket`, `estimate-ticket`)
+# ship an optional `evals/output-schema.yml` listing the `##`-headers
+# their output template MUST carry. The linter fails if a header drifts.
+
+_OUTPUT_SCHEMA_KEY_PATTERN = re.compile(r'^(\w+):\s*(.*?)\s*$')
+
+
+def parse_output_schema(text: str) -> dict:
+    """Tiny YAML-like parser for ``evals/output-schema.yml`` — no PyYAML dep.
+
+    Supported shape::
+
+        version: 1
+        required_headers:
+          - "Refined ticket"
+          - "Top-5 risks"
+
+    Unknown keys are preserved but ignored by :func:`lint_output_schema`.
+    """
+    result: dict = {}
+    current_list: Optional[str] = None
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith("- "):
+            if current_list is None:
+                continue
+            value = stripped[2:].strip().strip('"').strip("'")
+            result[current_list].append(value)
+            continue
+        match = _OUTPUT_SCHEMA_KEY_PATTERN.match(stripped)
+        if not match:
+            continue
+        key, value = match.group(1), match.group(2).strip('"').strip("'")
+        if value == "":
+            result[key] = []
+            current_list = key
+        else:
+            current_list = None
+            try:
+                result[key] = int(value)
+            except ValueError:
+                result[key] = value
+    return result
+
+
+def load_output_schema(skill_path: Path) -> Optional[dict]:
+    """Return the parsed schema sibling to ``skill_path`` or ``None``.
+
+    Lookup: ``<skill-dir>/evals/output-schema.yml``. Callers MUST use the
+    real path (not the repo-relative display path) so the sibling lookup
+    hits the actual directory.
+    """
+    if skill_path.name != "SKILL.md":
+        return None
+    schema_path = skill_path.parent / "evals" / "output-schema.yml"
+    if not schema_path.exists():
+        return None
+    try:
+        return parse_output_schema(schema_path.read_text(encoding="utf-8"))
+    except OSError:
+        return None
+
+
+def lint_output_schema(path: Path, text: str) -> List[Issue]:
+    """Fail if any required header declared in the sibling schema is
+    missing from the skill's output template.
+
+    No-op when the schema file does not exist or declares no
+    ``required_headers`` — keeps the check opt-in per skill.
+    """
+    schema = load_output_schema(path)
+    if schema is None:
+        return []
+    required = schema.get("required_headers") or []
+    if not isinstance(required, list) or not required:
+        return []
+    issues: List[Issue] = []
+    # Scan the whole skill text. Template headers live inside a fenced
+    # code block, but the `^## <header>$` line still matches — a drift
+    # (rename/removal) makes the line disappear from the file entirely.
+    for header in required:
+        if not isinstance(header, str) or not header.strip():
+            continue
+        pattern = re.compile(
+            rf"^##\s+{re.escape(header.strip())}\s*$", re.MULTILINE,
+        )
+        if not pattern.search(text):
+            issues.append(Issue(
+                "error", "output_schema_drift",
+                f"Output template is missing required header "
+                f"`## {header}` (declared in evals/output-schema.yml)",
+            ))
+    return issues
+
+
+# Artefact types that carry a JSON-Schema contract for their frontmatter.
+_SCHEMA_ARTEFACT_TYPES = {"skill", "rule", "command", "persona", "user-type"}
+
+
+def lint_frontmatter_schema(path: Path, text: str, artifact_type: str) -> List[Issue]:
+    """Validate the frontmatter of an artefact against its JSON-Schema.
+
+    Schemas live in ``scripts/schemas/``. One schema per artefact type;
+    see ``agents/reference/docs/frontmatter-contract.md`` for the human-readable
+    contract the schemas encode. Guidelines have no frontmatter and are
+    skipped.
+    """
+    if artifact_type not in _SCHEMA_ARTEFACT_TYPES:
+        return []
+    try:
+        schema = load_schema(artifact_type)
+    except FileNotFoundError:
+        return []
+
+    data, _ = parse_frontmatter_for_schema(text)
+    if data is None:
+        # Other linter checks already emit a missing-frontmatter error for
+        # rules/commands/personas; avoid double-reporting here.
+        return []
+
+    # Inject schema defaults before validating so artefacts that omit a field
+    # equal to its default (post abstraction-reduction migration) still satisfy
+    # `required` — mirrors validate_frontmatter's own loader path.
+    apply_schema_defaults(data, schema)
+
+    issues: List[Issue] = []
+    for error in validate_against_schema(data, schema):
+        code = f"schema_{error.rule}"
+        message = f"{error.path} – {error.message}"
+        issues.append(Issue("error", code, message))
+    return issues
+
+
+def lint_file(path: Path, repo_root: Path | None = None) -> LintResult:
+    # Skip README files — they are not lintable artifacts
+    if path.name.lower() == "readme.md":
+        return LintResult(
+            file=str(path),
+            artifact_type="unknown",
+            status="pass",
+            issues=[],
+            suggestions=[],
+        )
+    text = read_text(path)
+    artifact_type = detect_artifact_type(path, text)
+    # Use relative path for output if repo_root is provided
+    display_path = path
+    if repo_root:
+        try:
+            display_path = path.relative_to(repo_root)
+        except ValueError:
+            pass
+    if artifact_type == "skill":
+        result = lint_skill(display_path, text)
+    elif artifact_type == "rule":
+        result = lint_rule(display_path, text)
+    elif artifact_type == "command":
+        result = lint_command(display_path, text)
+    elif artifact_type == "guideline":
+        result = lint_guideline(display_path, text)
+    elif artifact_type == "persona":
+        result = lint_persona(display_path, text)
+    elif artifact_type == "user-type":
+        result = lint_usertype(display_path, text)
+    else:
+        # Frugality charter lives in contexts/ (artifact_type == unknown)
+        # but still needs Layer 2 index-integrity validation.
+        if _is_frugality_charter(path):
+            charter_issues = lint_frugality_charter_index(path, text)
+            return LintResult(
+                file=str(display_path),
+                artifact_type="unknown",
+                status=classify_status(charter_issues),
+                issues=charter_issues,
+                suggestions=[],
+            )
+        return lint_unknown(display_path, text)
+
+    # Post-processing: frontmatter schema validation (errors). Runs first
+    # so schema failures surface before the softer quality checks below.
+    schema_issues = lint_frontmatter_schema(display_path, text, artifact_type)
+    if schema_issues:
+        result.issues.extend(schema_issues)
+        result.status = classify_status(result.issues)
+
+    # Post-processing: interaction quality checks (warnings/info only)
+    interaction_issues = lint_interaction_quality(display_path, text)
+    if interaction_issues:
+        result.issues.extend(interaction_issues)
+        result.status = classify_status(result.issues)
+
+    # Post-processing: execution quality checks (errors/warnings)
+    execution_issues = lint_execution_quality(display_path, text)
+    if execution_issues:
+        result.issues.extend(execution_issues)
+        result.status = classify_status(result.issues)
+
+    # Post-processing: type boundary checks (warnings)
+    boundary_issues = lint_type_boundaries(display_path, text, artifact_type)
+    if boundary_issues:
+        result.issues.extend(boundary_issues)
+        result.status = classify_status(result.issues)
+
+    # Post-processing: verification maturity checks (warnings)
+    maturity_issues = lint_verification_maturity(display_path, text, artifact_type)
+    if maturity_issues:
+        result.issues.extend(maturity_issues)
+        result.status = classify_status(result.issues)
+
+    # Post-processing: governance and packaging checks (warnings)
+    governance_issues = lint_governance(path, text, artifact_type, repo_root)
+    if governance_issues:
+        result.issues.extend(governance_issues)
+        result.status = classify_status(result.issues)
+
+    # Post-processing: output-schema drift (errors). Skills only — schema
+    # lookup walks a sibling `evals/` directory off the real SKILL.md.
+    if artifact_type == "skill":
+        schema_issues = lint_output_schema(path, text)
+        if schema_issues:
+            result.issues.extend(schema_issues)
+            result.status = classify_status(result.issues)
+
+    # Post-processing: structural malice scan (errors). Skills, rules,
+    # and commands carry executable patterns; guidelines/personas are
+    # prose-only and skipped to keep noise low.
+    if artifact_type in ("skill", "rule", "command"):
+        malice_issues = check_structural_malice(text)
+        if malice_issues:
+            result.issues.extend(malice_issues)
+            result.status = classify_status(result.issues)
+
+    # Post-processing: frugality validator Layer 1 (writer-cite). Errors
+    # if a writer skill lacks the `## Frugality Standards` section or its
+    # link to the charter.
+    frugality_issues = lint_frugality_writer_cite(
+        display_path, text, artifact_type
+    )
+    if frugality_issues:
+        result.issues.extend(frugality_issues)
+        result.status = classify_status(result.issues)
+
+    return result
+
+
+def format_text(results: list[LintResult], quiet: bool = False) -> str:
+    lines: list[str] = []
+    # Phase 5.2: malice findings render in the spec shape
+    # ``<path>:<line>:malice:<pattern>:<matched>`` ahead of the badge
+    # block so security-failures are grep-able from the top.
+    malice_total = 0
+    for result in results:
+        for issue in result.issues:
+            if issue.code.startswith("malice:"):
+                pattern_name = issue.code.split(":", 1)[1]
+                lineno, _, matched = issue.message.partition(":")
+                lines.append(
+                    f"{result.file}:{lineno}:malice:{pattern_name}:{matched}"
+                )
+                malice_total += 1
+    if malice_total:
+        lines.append("")
+
+    # P10.5: quiet mode skips PASS-without-issues; malice + WARN/FAIL still rendered.
+    for result in results:
+        if quiet and result.status == "pass" and not result.issues and not result.suggestions:
+            continue
+        badge = {"pass": "[PASS]", "pass_with_warnings": "[WARN]", "fail": "[FAIL]"}[result.status]
+        lines.append(f"{badge} {result.file} ({result.artifact_type})")
+        if result.issues:
+            for issue in result.issues:
+                lines.append(f"  - {issue.severity.upper()} {issue.code}: {issue.message}")
+        else:
+            lines.append("  - No issues found")
+        if result.suggestions:
+            lines.append("  Suggested fixes:")
+            for suggestion in result.suggestions:
+                lines.append(f"    - {suggestion}")
+        lines.append("")
+
+    total = len(results)
+    fails = sum(1 for r in results if r.status == "fail")
+    warns = sum(1 for r in results if r.status == "pass_with_warnings")
+    passes = sum(1 for r in results if r.status == "pass")
+    suffix = f", {malice_total} malice" if malice_total else ""
+    lines.append(f"Summary: {passes} pass, {warns} warn, {fails} fail, {total} total{suffix}")
+    return "\n".join(lines)
+
+
+def format_json(results: list[LintResult]) -> str:
+    payload = {
+        "summary": {
+            "pass": sum(1 for r in results if r.status == "pass"),
+            "pass_with_warnings": sum(1 for r in results if r.status == "pass_with_warnings"),
+            "fail": sum(1 for r in results if r.status == "fail"),
+            "total": len(results),
+        },
+        "results": [
+            {
+                "file": r.file,
+                "artifact_type": r.artifact_type,
+                "status": r.status,
+                "issues": [asdict(issue) for issue in r.issues],
+                "suggestions": r.suggestions,
+            }
+            for r in results
+        ],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def check_condensation_pairs(root: Path) -> list[LintResult]:
+    """Check that every uncondensed skill/rule/command has a condensed counterpart and vice versa."""
+    results: list[LintResult] = []
+
+    pairs = [
+        ("skills", "SKILL.md", True),   # (subdir, filename, is_nested)
+        ("rules", "*.md", False),
+        ("commands", "*.md", False),
+    ]
+
+    for subdir, pattern, is_nested in pairs:
+        # ADR-017: union across every source root.
+        condensed_dir = root / "dist/agent-src" / subdir
+        uncondensed_names: set[str] = set()
+        any_source = False
+        for src_root in artefact_roots():
+            uncondensed_dir = src_root / subdir
+            if not uncondensed_dir.exists():
+                continue
+            any_source = True
+            if is_nested:
+                uncondensed_names |= {d.name for d in uncondensed_dir.iterdir() if d.is_dir() and (d / pattern).exists()}
+            else:
+                uncondensed_names |= {f.name for f in uncondensed_dir.glob(pattern) if f.is_file()}
+
+        if not any_source:
+            continue
+
+        # Collect names from condensed
+        if condensed_dir.exists():
+            if is_nested:
+                condensed_names = {d.name for d in condensed_dir.iterdir() if d.is_dir() and (d / pattern).exists()}
+            else:
+                condensed_names = {f.name for f in condensed_dir.glob(pattern) if f.is_file()}
+        else:
+            condensed_names = set()
+
+        # Missing condensed
+        for name in sorted(uncondensed_names - condensed_names):
+            path_str = f"dist/agent-src/{subdir}/{name}/{pattern}" if is_nested else f"dist/agent-src/{subdir}/{name}"
+            results.append(LintResult(
+                file=path_str,
+                artifact_type=subdir.rstrip("s"),
+                status="fail",
+                issues=[Issue("error", "missing_condensed", f"Uncondensed exists but condensed version is missing")],
+                suggestions=[f"Run /condense to generate dist/agent-src/{subdir}/{name}"],
+            ))
+
+        # Orphaned condensed (no source)
+        for name in sorted(condensed_names - uncondensed_names):
+            path_str = f"dist/agent-src/{subdir}/{name}/{pattern}" if is_nested else f"dist/agent-src/{subdir}/{name}"
+            results.append(LintResult(
+                file=path_str,
+                artifact_type=subdir.rstrip("s"),
+                status="fail",
+                issues=[Issue("error", "orphaned_condensed", f"Condensed exists but uncondensed source is missing")],
+                suggestions=[f"Delete orphaned file or restore uncondensed source"],
+            ))
+
+    return results
+
+
+def check_condensation_quality(root: Path) -> list[LintResult]:
+    """Check that condensed skills preserve key content from their uncondensed source."""
+    results: list[LintResult] = []
+    condensed_dir = root / "dist/agent-src" / "skills"
+    if not condensed_dir.exists():
+        return results
+
+    # ADR-017: collect skill dirs from every source root.
+    skill_sources: list[Path] = []
+    for src_root in artefact_roots():
+        uncondensed_dir = src_root / "skills"
+        if uncondensed_dir.exists():
+            skill_sources.extend(sorted(uncondensed_dir.iterdir()))
+    if not skill_sources:
+        return results
+
+    # Sections that MUST exist in condensed if they exist in uncondensed
+    preserved_sections = ["When to use", "Procedure", "Gotcha", "Gotchas", "Do NOT", "Output format", "Output"]
+
+    for skill_dir in skill_sources:
+        src = skill_dir / "SKILL.md"
+        dst = condensed_dir / skill_dir.name / "SKILL.md"
+        if not src.exists() or not dst.exists():
+            continue
+
+        src_text = read_text(src)
+        dst_text = read_text(dst)
+        src_sections = extract_sections(src_text)
+        dst_sections = extract_sections(dst_text)
+
+        issues: list[Issue] = []
+        suggestions: list[str] = []
+
+        # Check required sections survived condensation
+        for section in preserved_sections:
+            if section_matches(section, src_sections) and not section_matches(section, dst_sections):
+                issues.append(Issue("warning", "condensation_lost_section",
+                                    f"Condensed version lost '{section}' section"))
+
+        # Check validation keywords survived
+        src_proc = find_procedure_block(src_text) or ""
+        dst_proc = find_procedure_block(dst_text) or ""
+        validation_patterns = [r"\bverif", r"\bcheck\b", r"\bconfirm\b", r"\bvalidat", r"\binspect"]
+        src_has_validation = any(re.search(p, src_proc, re.IGNORECASE) for p in validation_patterns)
+        dst_has_validation = any(re.search(p, dst_proc, re.IGNORECASE) for p in validation_patterns)
+        if src_has_validation and not dst_has_validation:
+            issues.append(Issue("warning", "condensation_lost_validation",
+                                "Condensed procedure lost validation keywords present in uncondensed"))
+
+        # Check code blocks / examples survived
+        src_code_blocks = len(re.findall(r"```", src_text))  # pairs of ``` = blocks
+        dst_code_blocks = len(re.findall(r"```", dst_text))
+        if src_code_blocks > 0 and dst_code_blocks < src_code_blocks // 2:
+            issues.append(Issue("warning", "condensation_lost_example",
+                                f"Condensed version has fewer code blocks "
+                                f"({dst_code_blocks // 2} vs {src_code_blocks // 2} in source)"))
+
+        # Check anti-pattern / "Do NOT" bullets survived
+        src_donot = len(re.findall(r"(?:Do NOT|NEVER|MUST NOT)\b", src_text))
+        dst_donot = len(re.findall(r"(?:Do NOT|NEVER|MUST NOT)\b", dst_text))
+        if src_donot > 0 and dst_donot < src_donot // 2:
+            issues.append(Issue("warning", "condensation_lost_antipattern",
+                                f"Condensed version lost anti-pattern constraints "
+                                f"({dst_donot} vs {src_donot} in source)"))
+
+        if issues:
+            rel_path = f"dist/agent-src/skills/{skill_dir.name}/SKILL.md"
+            results.append(LintResult(
+                file=rel_path,
+                artifact_type="skill",
+                status="pass_with_warnings",
+                issues=issues,
+                suggestions=suggestions or ["Re-condense to preserve lost content"],
+            ))
+
+    return results
+
+
+def check_duplication(root: Path) -> list[LintResult]:
+    """Detect skills with highly similar names or descriptions."""
+    results: list[LintResult] = []
+    # ADR-017: collect skill dirs across every source root, dedup by name.
+    skill_dirs: list[Path] = []
+    seen: set[str] = set()
+    for src_root in artefact_roots():
+        sd = src_root / "skills"
+        if not sd.exists():
+            continue
+        for d in sorted(sd.iterdir()):
+            if d.is_dir() and d.name not in seen:
+                seen.add(d.name)
+                skill_dirs.append(d)
+    if not skill_dirs:
+        return results
+
+    # Collect all skill names and descriptions
+    skill_data: list[tuple[str, str, Path]] = []
+    for skill_dir in skill_dirs:
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.exists():
+            continue
+        text = read_text(skill_file)
+        desc = extract_description(text) or ""
+        skill_data.append((skill_dir.name, desc.lower(), skill_file))
+
+    # Check for name prefix overlap (e.g. "laravel" and "laravel-validation")
+    # Only flag if descriptions are also similar
+    for i, (name_a, desc_a, path_a) in enumerate(skill_data):
+        for name_b, desc_b, path_b in skill_data[i + 1:]:
+            # Skip known patterns: skill-X and skill-X-subtype is intentional
+            if name_a == name_b:
+                continue
+            # Check description word overlap
+            if desc_a and desc_b:
+                words_a = set(desc_a.split())
+                words_b = set(desc_b.split())
+                if len(words_a) > 3 and len(words_b) > 3:
+                    overlap = len(words_a & words_b) / min(len(words_a), len(words_b))
+                    if overlap > 0.7:
+                        rel_a = f".agent-src.uncondensed/skills/{name_a}/SKILL.md"
+                        results.append(LintResult(
+                            file=rel_a,
+                            artifact_type="skill",
+                            status="pass_with_warnings",
+                            issues=[Issue("warning", "similar_description",
+                                         f"Description highly similar to '{name_b}' ({overlap:.0%} word overlap)")],
+                            suggestions=[f"Consider merging with '{name_b}' or differentiating descriptions"],
+                        ))
+
+    return results
+
+
+def compute_exit_code(results: list[LintResult], strict_warnings: bool) -> int:
+    # Phase 5.2: structural-malice findings emit exit code 3 (security-
+    # failure), distinct from 2 (build-failure) so CI surfaces can split.
+    for r in results:
+        if any(issue.code.startswith("malice:") for issue in r.issues):
+            return 3
+    if any(r.status == "fail" for r in results):
+        return 2
+    if any(r.status == "pass_with_warnings" for r in results) and strict_warnings:
+        return 1
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Lint skills and rules.")
+    parser.add_argument("paths", nargs="*", help="Files to lint")
+    parser.add_argument("--all", action="store_true", help="Lint all skills/rules in the repo")
+    parser.add_argument("--changed", action="store_true", help="Lint changed skills/rules")
+    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format")
+    parser.add_argument("--pairs", action="store_true", help="Check condensation pairs (uncondensed vs condensed)")
+    parser.add_argument("--duplicates", action="store_true", help="Detect skills with similar descriptions")
+    parser.add_argument("--condensation-quality", action="store_true", help="Check condensed skills preserve key content")
+    parser.add_argument("--strict-warnings", action="store_true", help="Return non-zero on warnings")
+    parser.add_argument("--report", action="store_true", help="Output quality score report")
+    parser.add_argument("--repo-root", default=".", help="Repository root")
+    parser.add_argument("--quiet", action="store_true",
+                        help="suppress per-file PASS lines; keep malice + WARN/FAIL + summary (P10.5)")
+    return parser.parse_args()
+
+
+def format_report(results: list[LintResult]) -> str:
+    """Generate a quality score report grouped by artifact type."""
+    lines = ["# Quality Report", ""]
+
+    # Group by artifact type
+    by_type: dict[str, list[LintResult]] = {}
+    for r in results:
+        by_type.setdefault(r.artifact_type, []).append(r)
+
+    # Summary table
+    lines.append("| Type | Total | Pass | Warn | Fail | Score |")
+    lines.append("|---|---|---|---|---|---|")
+    total_score = 0.0
+    total_count = 0
+    for atype in sorted(by_type):
+        items = by_type[atype]
+        n = len(items)
+        n_pass = sum(1 for r in items if r.status == "pass")
+        n_warn = sum(1 for r in items if r.status in ("warn", "pass_with_warnings"))
+        n_fail = sum(1 for r in items if r.status == "fail")
+        # Score: pass=10, warn=8, fail=3
+        type_score = (n_pass * 10 + n_warn * 8 + n_fail * 3) / max(n, 1)
+        total_score += type_score * n
+        total_count += n
+        lines.append(f"| {atype} | {n} | {n_pass} | {n_warn} | {n_fail} | {type_score:.1f}/10 |")
+    overall = total_score / max(total_count, 1)
+    lines.append(f"| **TOTAL** | **{total_count}** | | | | **{overall:.1f}/10** |")
+
+    # Top issues
+    issue_counts: dict[str, int] = {}
+    for r in results:
+        for i in r.issues:
+            issue_counts[i.code] = issue_counts.get(i.code, 0) + 1
+    if issue_counts:
+        lines.extend(["", "## Top Issues", ""])
+        lines.append("| Issue | Count | Severity |")
+        lines.append("|---|---|---|")
+        for code, count in sorted(issue_counts.items(), key=lambda x: -x[1])[:15]:
+            # Find severity from first occurrence
+            sev = "?"
+            for r in results:
+                for i in r.issues:
+                    if i.code == code:
+                        sev = i.severity
+                        break
+                if sev != "?":
+                    break
+            lines.append(f"| `{code}` | {count} | {sev} |")
+
+    # Files with most issues (top 10)
+    files_with_issues = [
+        (r.file, len(r.issues), r.status)
+        for r in results
+        if r.issues
+    ]
+    files_with_issues.sort(key=lambda x: -x[1])
+    if files_with_issues:
+        lines.extend(["", "## Files with Most Issues (Top 10)", ""])
+        lines.append("| File | Issues | Status |")
+        lines.append("|---|---|---|")
+        for fpath, count, status in files_with_issues[:10]:
+            short = fpath.replace(".agent-src.uncondensed/", "")
+            lines.append(f"| `{short}` | {count} | {status} |")
+
+    # Per-file quality breakdown (skills only)
+    skill_results = [r for r in results if r.artifact_type == "skill" and "/pair-check/" not in r.file]
+    if skill_results:
+        lines.extend(["", "## Per-File Quality (Skills)", ""])
+        lines.append("| Skill | Structure | Validation | Scope | Dependency | Lines |")
+        lines.append("|---|---|---|---|---|---|")
+        for r in sorted(skill_results, key=lambda x: x.file):
+            short = r.file.replace(".agent-src.uncondensed/skills/", "").replace("dist/agent-src/skills/", "").replace("/SKILL.md", "")
+            codes = {i.code for i in r.issues}
+
+            # Structure: fail if missing required sections
+            struct = "❌" if codes & {"missing_section", "empty_procedure", "unordered_procedure"} else "✅"
+
+            # Validation: weak if missing or vague
+            if codes & {"missing_validation", "vague_validation"}:
+                valid = "❌ weak"
+            elif codes & {"missing_inspect_step"}:
+                valid = "⚠️ partial"
+            else:
+                valid = "✅ strong"
+
+            # Scope: broad if flagged
+            scope = "⚠️ broad" if "broad_scope" in codes else "✅ focused"
+
+            # Guideline dependency
+            if "guideline_dependent_skill" in codes:
+                dep = "❌ high"
+            elif "pointer_only_skill" in codes:
+                dep = "⚠️ medium"
+            else:
+                dep = "✅ low"
+
+            # Line count
+            total_lines = 0
+            try:
+                total_lines = Path(r.file).read_text(encoding="utf-8").count("\n")
+            except OSError:
+                pass
+
+            lines.append(f"| `{short}` | {struct} | {valid} | {scope} | {dep} | {total_lines} |")
+
+    return "\n".join(lines)
+
+
+def main() -> int:
+    args = parse_args()
+    root = Path(args.repo_root).resolve()
+
+    try:
+        paths: list[Path] = []
+        if args.all or args.report:
+            paths.extend(gather_all_candidate_files(root))
+        if args.changed:
+            paths.extend(gather_changed_candidate_files(root))
+        for raw in args.paths:
+            path = (root / raw).resolve() if not Path(raw).is_absolute() else Path(raw)
+            if not path.exists():
+                continue
+            if path.is_dir():
+                # Walk the directory like a source root so callers can pass
+                # `packages/pack-laravel/.agent-src.uncondensed/` (ADR-017 Phase 4.4).
+                paths.extend(gather_candidate_files_under(path))
+            else:
+                paths.append(path)
+
+        paths = sorted(set(paths))
+        if not paths:
+            # Emit a valid empty payload when a structured format was requested
+            # so downstream parsers (e.g. PR-summary workflows) don't fail on an
+            # empty stdout. stderr keeps the human-readable note.
+            if args.report:
+                print(format_report([]))
+            elif args.format == "json":
+                print(format_json([]))
+            print("No matching skill/rule files found.", file=sys.stderr)
+            return 0
+
+        results = [lint_file(path, repo_root=root) for path in paths]
+
+        # Additional checks
+        if args.pairs or args.report:
+            results.extend(check_condensation_pairs(root))
+        if args.duplicates:
+            results.extend(check_duplication(root))
+        if args.condensation_quality or args.report:
+            results.extend(check_condensation_quality(root))
+
+        if args.report:
+            print(format_report(results))
+        elif args.format == "json":
+            print(format_json(results))
+        else:
+            print(format_text(results, quiet=args.quiet))
+
+        return compute_exit_code(results, strict_warnings=args.strict_warnings)
+
+    except Exception as exc:  # noqa: BLE001
+        print(f"Internal error: {exc}", file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())