Holusight

Holusight is a small read-only consistency helper for agents. Graphify supplies the map; Holusight checks graph references and rescans current source for code/code and docs/docs duplication candidates and explicitly linked code/docs/code facts. It does not index documents, synthesize answers, infer arbitrary prose truth, call models/network services, edit source, or silently rebuild Graphify.

Install

Requires Python 3.11+; Git is needed to verify graph provenance. From a checkout, run uv sync (or pip install -e .). The runtime has no Python dependencies. Development tooling uses uv sync --extra dev. Offline commands below require an already provisioned environment. The installed console entry point is holus; the former skill installer and retrieval commands are retired.

Related MCP server: semantic-search-mcp

Run

Replace [repo-path] with the repository root or omit it for the current directory.

uv run --offline python -m holusight check [repo-path]
uv run --offline python -m holusight check [repo-path] --scope specs/
uv run --offline holus check [repo-path] --docs
uv run --offline python -m holusight status [repo-path]
uv run --offline holus align [repo-path]
# after installation: holus check [repo-path] / holus align [repo-path]

Output is JSON. status reports whole-graph provenance, not integrity; use check for errors. A current graph requires a matching build commit, clean Git tree and graph-backed source bytes verified against that snapshot. Unverifiable sources are unknown, not fresh. See the provenance contract for exact conditions. The historical graph here is intentionally not refreshed during checks; expect stale until an operator rebuilds it independently. For check, exit 0 requires current provenance with no errors/unverified checks in declared coverage; exit 1 covers errors, stale, unknown or unavailable. Error findings in non-current graphs are leads, not a current clean bill of health.

Graph integrity and literal source/path evidence are bounded checks, not semantic doc/code verification. A missing path immediately annotated (not created yet) (for example, `src/future.py` (not created yet)) is an informational planned_path_reference, not a confirmed current-reference error. It counts as unverified: a proposal-only scope returns unknown, not a clean semantic verdict. This literal path-local annotation does not infer intent from words like “future” elsewhere or exempt unsafe paths. Agents should inspect cited source lines and use Graphify directly for traversal. No source or graph files are written by check or align.

Duplication, explicit alignment, and updates

holus align rescans current Python and Markdown files with no cache or daemon. It reports Python function AST copies/renamed-local candidates and substantive duplicate/overlapping Markdown paragraphs. Candidates require agent judgment: similar code may be intentionally separate. It preserves literals, operators and external identifiers; unsupported languages and arbitrary prose meaning are not verified.

Check coverage.extensions, unsupported_files and focused_unsupported_files before interpreting results. Recognized unsupported application sources (including TypeScript and Swift) are inventoried by path metadata only, not parsed or hashed by the source scanner. If selected, they make the report partial, complete: false, exit 1, even when useful Python candidates remain. An empty inventory is never complete. The extension list is not exhaustive; ok means only the declared supported checks completed, not that the repository has no bad code. A Python-only scope or --docs can finish its narrower checks while explicitly retaining whole-inventory unsupported counts. Graph provenance is separate and may inspect graph-backed source files.

Use this as a limited candidate-navigation helper, not a general clone detector, architectural-quality gate or automatic refactoring tool. Public semantic-clone subsets had very low recall; see evaluation scope and results.

For a fact that must agree across consumers, explicitly give it the same key:

MAX_RETRIES = 3
# holus:fact retry-limit = MAX_RETRIES

<!-- holus:fact retry-limit = 5 -->

Different declarations of that key produce a mismatch with source hashes and locations across code/code, docs/docs or docs/code. Markers compare declarations, not surrounding prose. Python markers must be module-level; unsupported or malformed declarations are unverified, not executed. Source scans and graph freshness are separate: alignment can finish while the graph remains stale. See the deterministic source contract for binding, example-filtering and concurrent-edit limits.

Agents can inspect findings, edit the cited source, and rerun:

mkdir -p .holusight
holus align . > .holusight/before.json  # exit 1 for explicit mismatch/incomplete scan
# inspect cited files/lines and repair them (Holusight never edits them)
holus align . --against .holusight/before.json > .holusight/after.json

Focus the agent's findings, without losing comparison partners:

holus check . --docs                  # supported Markdown anywhere in safe enumeration
holus align . --scope specs/          # findings involving specs and relevant outside partners
holus align . --scope src/holusight/  # application code and relevant documentation
holus align . --docs --scope specs/  # intersection: Markdown beneath specs

The positional path stays the repository root, not the focus folder. File/directory scopes normalize trailing slashes and use path-component boundaries. status stays whole-graph provenance and rejects targeting flags. --docs does not enter ignored/private archives or follow source symlinks. check restricts source checks and graph integrity to selected items/incident links; its coverage explicitly says global integrity is not checked. align limits emitted findings, not comparison inventory: partners elsewhere and unverified partner evidence still matter. Reports expose the normalized selector and focused-file coverage. Empty/unrepresented selections are unknown/partial, never a clean pass. Focus reduces irrelevant findings the agent sees; it does not prove fewer scanner reads or improved productivity. Scope is not a privacy boundary. For a mixed private vault, first make an independently allowlisted, regular-file, code-only snapshot outside the vault, then scan that snapshot locally with egress disabled. Do not point the scanner at the whole vault, even with --scope.

Reports include content hashes and delta.new/resolved/persisting IDs plus changed/deleted source paths. Resolved means no longer detected, not behaviorally correct. Analyzer rules are holus-alignment/v3; v1/v2 receipts must be regenerated and cannot establish resolution under corrected normalization/coverage. Comparison refuses incompatible or incomplete baselines; see receipt compatibility and scan limits. Duplicate-only review is advisory (exit 0); mismatch, partial, unknown and unavailable exit 1. There is no automatic skill selection or background Graphify refresh.

Development

See the development playbook for setup, tests and lint commands.

See ARCHITECTURE.md, specs/028-graphify-consistency-helper.md and specs/029-deterministic-duplication-alignment.md for the supported contracts, research and migration disposition. Earlier numbered specs and accepted decisions are historical context for the retired retrieval product, not current interfaces.