v1.0 to v1.0

---

name: ls-markdown-reference-validator

description: "Use when validating repository Markdown local references and anchors; scheduled-safe YAML-configured reports keep host-aware scans explicit and local-only."

metadata:

version: "1.0"

compatibility: "Python 3.12+, PyYAML. Config-driven targets and Kilo manifest discovery."

---

# Markdown reference validator

Validate repository Markdown reference integrity across Localsetup docs, skills, templates, and repository documentation.

## Purpose

- Parse markdown files from configured paths/globs.

- Validate local reference targets from markdown links and inline code paths.

- Validate markdown `#anchor` fragments against heading slugs.

- Write a durable markdown report for AI agents and humans.

- Run safely on schedule with interval guard and optional jitter.

## Why this exists

Framework and ops docs evolve quickly. Broken references waste agent cycles and reduce reliability. This skill provides a deterministic, zero-token integrity check that can run in cron/login automation and produce one report location agents can inspect.

## Inputs and outputs

- **Input config (YAML):** `ls/skills/ls-markdown-reference-validator/templates/markdown_reference_audit.yaml`, or a repo-local copy adapted from it.

- **Strict repo profile:** `ls/skills/ls-markdown-reference-validator/templates/markdown_reference_strict_repo.yaml`

- **Host-aware profile:** `ls/skills/ls-markdown-reference-validator/templates/markdown_reference_host_aware.yaml`

- **Skill entrypoint:** `scripts/markdown_reference_audit.py`

- **Engine script:** `ls/skills/ls-markdown-reference-validator/scripts/markdown_reference_validator.py`

- **Default report:** .localsetup/state/markdown-reference/default.md (ignored local state)

- **Default run-state marker:** .localsetup/state/markdown-reference/default-last-run-epoch (ignored local state)

## Typical commands

Run once manually:

```bash

python3 ls/skills/ls-markdown-reference-validator/scripts/markdown_reference_audit.py \

--force \

--reason manual

```

Run the strict repo-owned profile:

```bash

python3 ls/skills/ls-markdown-reference-validator/scripts/markdown_reference_audit.py \

--config ls/skills/ls-markdown-reference-validator/templates/markdown_reference_strict_repo.yaml \

--force \

--reason manual

```

Run the explicit host-aware profile (its report stays in ignored local state and outside-repository paths are redacted):

```bash

python3 ls/skills/ls-markdown-reference-validator/scripts/markdown_reference_audit.py \

--config ls/skills/ls-markdown-reference-validator/templates/markdown_reference_host_aware.yaml \

--force \

--reason manual

```

Run with login jitter (3-5 min):

```bash

python3 ls/skills/ls-markdown-reference-validator/scripts/markdown_reference_audit.py \

--reason login-autostart \

--jitter-min-seconds 180 \

--jitter-max-seconds 300

```

## Scheduling model

Recommended defaults:

- **Periodic:** every 12 hours (cron trigger).

- **Login:** run once at user login with random delay 3-5 minutes.

Use `ls-cron-orchestrator` with a user-created manifest (for example `cron/manifest.yaml` in the target repo) for periodic trigger, and XDG autostart desktop entry for login trigger. This skill does not ship a cron manifest.

## Config model (YAML sidecar)

The sidecar config defines:

- `targets[]`: each with `base_dir`, `include_globs`, optional `exclude_globs`.

- `kilo_manifest_discovery.manifests[]`: `kilo.json` or `kilo.jsonc` paths to discover additional instruction/skills markdown surfaces. JSONC manifests may use comments and trailing commas.

- `report.output_path`, `report.state_file`, and `report.max_findings`.

- `extraction.inline_code_mode`: `off | smart | all` (`smart` is default and recommended).

- `ignore.*` blocks to reduce false positives from templates/examples while keeping strict checks for concrete links.

The shipped default profile is repo-only and writes report/state only beneath ignored .localsetup/state/markdown-reference/. Use the strict repo profile for narrower tracked-source link and anchor review. Use the host-aware profile only when you explicitly need local adapter or host instruction surfaces; its report remains local-only and redacts paths outside repo_root.

### Config schema (practical defaults)

```yaml

extraction:

inline_code_mode: smart

# Back-compat toggle: if inline_code_mode omitted, true => smart / false => off

include_inline_code_paths: true

ignore:

# Skip scanning these markdown sources entirely.

source_file_globs:

- "**/node_modules/**"

- "**/.kilo/state/**"

- "**/.kilo/plans/**"

# Skip targets matching any regex (examples/placeholders/snippets).

target_regexes:

- '^URL$'

- '^<[^>]+>$'

- '^\$[A-Za-z_][A-Za-z0-9_]*(/.*)?$'

# Skip targets starting with these prefixes.

path_prefixes:

- "/etc/"

- "old.reddit.com/"

# Skip targets containing these placeholder tokens.

placeholder_tokens:

- "<repo>"

- "{slug}"

- "YYYY-MM-DD"

```

### Example snippet

```yaml

targets:

- name: framework-docs-and-skills

base_dir: "{repo_root}"

include_globs:

- "ls/docs/**/*.md"

- "ls/skills/**/*.md"

- "ls/templates/**/*.md"

kilo_manifest_discovery:

manifests:

- "{repo_root}/kilo.jsonc"

- "/home/user/.config/kilo/kilo.jsonc"

```

## Validation behavior

- Skips external URLs (`http`, `https`, `mailto`, etc.).

- Resolves relative targets from the source file's directory.

- Also tries repo-root resolution for repo-absolute style links like `ls/...` or `docs/...`.

- Applies ignore controls in this order: source glob skip -> placeholder/prefix/regex/pseudo-path skip -> strict path/anchor checks.

- Validates config section shapes up front and reports schema errors instead of raw tracebacks.

- Reports unreadable source markdown, anchor targets, and state files instead of treating them as clean results.

- Flags:

- `missing_path`

- `missing_anchor`

- `unreadable_source`

- `unreadable_anchor_target`

- Includes Kilo manifest discovery notes in report for observability.

## Safety and hardening

- Input hostile-by-default handling.

- Sanitized text fields and bounded lengths.

- Interval guard to avoid noisy repeated runs.

- Optional jitter to reduce post-login contention.

## Related references

- `ls/docs/TOOLING_POLICY.md`

- `ls/docs/INPUT_HARDENING_STANDARD.md`

- `ls/skills/ls-cron-orchestrator/SKILL.md`