fix: allow candidate-level stale reference suppressions

[dd3ok]

Summary

• add optional candidate matching for stale-reference entries in lucid.ignore.json
• keep broad rule/path suppressions compatible while allowing reviewed false positives to be suppressed without hiding other missing references in the same file
• add a regression fixture and suppress Lucid README archive-internal path false positives with candidate-scoped entries

Testing

• python3 scripts/validate-skill.py
• python3 scripts/validate-no-dangerous-io.py
• python3 scripts/validate-evals.py
• python3 scripts/validate-docs.py
• python3 scripts/validate-package-skill.py
• python3 skills/lucid/scripts/lucid.py verify --root . --strict
• python3 skills/lucid/scripts/lucid.py audit --root . --format terminal

[gemini-code-assist]

Code Review

This pull request introduces candidate-level suppressions for the stale-reference rule, allowing users to narrow down suppressions to specific missing reference candidates rather than suppressing all missing references in a file. This includes updating the documentation, validation scripts, fixtures, and the core suppression matching logic in skills/lucid/scripts/lucid.py. Feedback was provided to optimize the apply_suppressions function; the current implementation performs a linear scan over all suppressions for each finding, resulting in O(N * M) complexity, which can be optimized to O(N + M) by grouping suppressions by (rule, path) in a dictionary lookup.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The current implementation of apply_suppressions performs a linear scan (O(M)) over all suppressions for every single finding, resulting in an O(N * M) time complexity.

By grouping the suppressions by (rule, path) in a dictionary lookup, we can reduce the search space to only the relevant suppressions for each finding, optimizing the average-case lookup time to O(1) per finding and overall complexity to O(N + M).

Suggested change

	active: list[dict[str, Any]] = []
	suppressed: list[dict[str, Any]] = []
	for finding in findings:
	suppression = suppression_lookup.get((finding["rule"], finding["path"]))
	suppression = next(
	(
	item
	for item in suppressions
	if finding_matches_suppression(finding, item)
	),
	None,
	)
	suppression_lookup: dict[tuple[str, str], list[dict[str, str]]] = {}
	for item in suppressions:
	suppression_lookup.setdefault((item["rule"], item["path"]), []).append(item)
	active: list[dict[str, Any]] = []
	suppressed: list[dict[str, Any]] = []
	for finding in findings:
	candidates = suppression_lookup.get((finding["rule"], finding["path"]), [])
	suppression = next(
	(
	item
	for item in candidates
	if finding_matches_suppression(finding, item)
	),
	None,
	)