Cohere.Drift (Cohere v0.1.0)

Copy Markdown View Source

The drift sentinel: mechanically detects when the project has moved out from under its coherence artifacts.

Four checks, all deterministic:

  1. Stale map — the committed cohere/map.md no longer matches a fresh derivation. The code changed shape; the map needs regenerating.
  2. Drifted cards — a context's public surface no longer matches the surface its intent card was reviewed against. Someone (or something) must re-review: fix the card, or accept the drift with a dated annotation.
  3. Broken references — a card mentions MyApp.Module or MyApp.Module.fun/1 that no longer exists.
  4. Stale derived artifacts — a registered generated-and-committed output (config :cohere, derived: [...]) no longer matches a fresh render. The map generalized: same severity, same byte-compare (DEC-DER-001 in cohere/design/derived-artifacts.md).

Accepted drift is documented drift; silent drift is the failure mode.

Summary

Functions

check(project)

Runs all drift checks. Returns a %Report{}.

derived_status(project, other)

Freshness of one registered derived artifact: renders it into a scratch directory under the build path (never the working tree) and byte-compares the tree against the committed path.

format(report)

Formats a report's findings for terminal/CI output. No verdict line — Cohere.Check.format/1 owns the verdict, since drift findings are one category among the checks it composes.

Functions

check(project)

@spec check(Cohere.Project.t()) :: Cohere.Drift.Report.t()

Runs all drift checks. Returns a %Report{}.

derived_status(project, other)

@spec derived_status(
  Cohere.Project.t(),
  {String.t(), String.t(), {module(), atom()}, String.t()}
) ::
  map()

Freshness of one registered derived artifact: renders it into a scratch directory under the build path (never the working tree) and byte-compares the tree against the committed path.

The registration is {name, path, {module, function}, fix} where function(out_dir) renders the artifact as it would appear at path, and fix is the command the finding prints. Returns %{name, path, status: :fresh | :stale | :missing, delta, more, fix} with a bounded file-level delta (DEC-DER-004: which files differ, appear, or vanish — the fixing command is the payload).

format(report)

Formats a report's findings for terminal/CI output. No verdict line — Cohere.Check.format/1 owns the verdict, since drift findings are one category among the checks it composes.