stacklok / stacklok/matlatl

Backticked prose code-path liveness (phase 2 only — linked code paths already checked in core)

Open
#24 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Why

Docs constantly reference code by path — internal/domain/graphmodel/scent.go, cmd/matlatl, config file names — in prose, backticks, and links. When code moves, those references rot silently: check only validates markdown-to-markdown links. Stale code paths are the doc rot that hurts agents most, because agents act on them (open the file, cite the path, edit the wrong place), burning tool calls or producing wrong output.

This also surfaced as one of the original dogfood findings from running matlatl on real repos.

What to build

  1. Validate markdown links whose target is a non-markdown repo file (currently classified non-note): the target must exist within the root. Likely cheap — resolution machinery exists; this may be a severity/classification change plus an existence check.
  2. Optionally (phase 2, config-gated): scan backticked inline code spans that look path-like (contains '/' and an extension, or matches a configured prefix like internal/) and check existence. Higher false-positive risk — needs dogfooding and probably an allowlist.
  3. New finding kind stale-code-reference (Warning for real links, Info for backtick prose), respecting root containment (ADR 0003 — never stat outside the scan root).

Determinism

Pure filesystem-presence data captured at scan time (the scanner already walks the tree); no network, byte-stable.

🤖 Generated with Claude Code

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing markdown link resolution and scanner machinery, then review ADR 0003 for root-containment rules. Run the current check against a repository with non-markdown links and backticked paths. Done means valid repository-file links are checked deterministically and findings use the specified kind and severities, with phase-2 prose scanning gated or explicitly scoped.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, devtools, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.