LookoutCheap, honest drift detection for sources you re-check over time, built on Forage snapshots.

Lookout Agent Guidance#

Lookout is @kontourai/lookout: a source registry and non-throwing drift-check runner over Forage snapshots. It classifies each source into exactly one of four CheckResult kinds (unchanged-304, unchanged-hash, changed, error) and exposes a machine-readable JSONL CLI. Lookout owns the prior-vs-fresh hash comparison, classification, and snapshot persistence; Forage owns fetch politeness/robots/redirects/timeout, snapshot mechanics, and durable reference integrity. Scheduling stays external. The runner NEVER throws.

Source Of Truth#

  • Vocabulary: CONTEXT.md; the L1 contract decision: docs/decisions/l1-registry-and-results.md (index regenerated by npm run gen:decisions-index).
  • Library source in src/; the thin bin shim is bin/lookout.mjs.
  • dist/ is generated by npm run build (tsc); do not hand-edit it.
  • Trustworthy unchanged-304 requires Forage's validator-scoped revalidation; do not bypass @kontourai/forage/fetch or reconstruct snapshot references in Lookout. Traverse remains exact-pinned for its schema/proposal contracts.
  • Public repo: newly authored source, tests, docs, and config stay content-boundary-clean (generic illustrative names/URLs only, no private vertical vocabulary); npm run check:content-boundary enforces this. The scripts/check-content-boundary.cjs gate is a temporary per-repo copy pending kontourai/veritas#112 centralization.

Match Checks To Change Type#

  • Library/types changes: npm test (build + Node tests against dist/).
  • Package-shape/exports/bin changes: npm run check:pack.
  • Docs/decision changes: npm run check:decisions (and regenerate the index with npm run gen:decisions-index when a decision file changes).
  • Docs are published with docs-kit: docs-kit.json lists the published docs and MCP topics, and npm run docs:check is the gate. When you change code a document covers, update that document.
  • Content/fixture changes: npm run check:content-boundary.
  • Anything before push: npm run verify (content-boundary + decisions + typecheck + test + pack sanity — the exact chain CI's verify job runs).
  • Releases use release-please with conventional commits; the version lives in .release-please-manifest.json and package.json.

Useful Commands#

  • npm run verify · npm test · npm run typecheck · npm run check:pack · npm run check:decisions · npm run check:content-boundary

This repo uses Veritas for AI governance. Read .veritas/GOVERNANCE.md before making changes. After changes, run npm exec --yes --package=@kontourai/veritas@1.5.2 -- veritas readiness and address any FAIL lines before finishing.

Source: AGENTS.md