lint-markdown

Purpose

Execute Python-based markdown validation with three-tier classification based on taxonomy-rfc.md: STRICT files require full compliance with LLM-facing standards, MODERATE files apply governance rules, and LIGHT files receive basic validation.

IO Semantics

Input: File paths, directories, or global workspace scope with optional parameters.

Output: Structured linting reports with issue categorization, severity levels, and auto-fix suggestions when applicable.

Side Effects: Updates target files when using --fix parameter, generates structured reports in JSON or human-readable format.

Deterministic Steps

1. Environment Validation

• Verify Python 3 availability.
• Confirm validator script exists at skills/llm-governance/scripts/validator.py.
• Validate config.yaml exists and loads properly.

2. File Classification

• Apply STRICT classification to LLM-facing files: commands//*.md, skills//SKILL.md, agents//AGENT.md, rules//*.md, AGENTS.md, CLAUDE.md
• Apply MODERATE classification to governance files: governance//*.md, config-sync//.md, agent-ops/**/.md
• Apply LIGHT classification to remaining markdown files.
• Exclude human-facing docs: docs/, examples/, tests/, ide/

3. Validation Execution

• Run Python validator based on requested mode: python3 skills/llm-governance/scripts/validator.py for standard validation python3 skills/llm-governance/scripts/validator.py for JSON output (future)
• Parse validator output and categorize issues by severity and type.

4. Report Generation

• Aggregate results by file classification and issue type.
• Generate structured summary with:
  • Total issue count and severity breakdown
  • Classification-specific compliance metrics
  • Auto-fix success rate where applicable
• Provide actionable recommendations organized by priority.

5. Validation Compliance

• Ensure all processing respects skills/llm-governance/rules/99-llm-prompt-writing-rules.md constraints.
• Apply imperative communication patterns in all output.
• Maintain 100-character line limits in generated reports.

Safety Constraints

• Never modify files without explicit --fix parameter.
• Preserve original file content through backup mechanisms when fixing.
• Respect file exclusions and never scan excluded directories.
• Validate tool chain compatibility before executing validator.