@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/skill_linter.py

@@ -1,3694 +0,0 @@
-#!/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())