docs-drift-check Reference

The Loom workflow that watches whether this docs site has drifted from the codebase it describes. Source: optimalOS/workflows/docs-drift-check.ts.

What it is

A smoke detector. Each page on docs.optimal.miami was written from a set of audit JSONs at ~/.optimalos/transfers/docs-audit/*.json, and every claim in those JSONs is pinned to a source path with a line number. This workflow walks those evidence paths every six hours, stats each file, and counts how many have been modified since the audit was taken (drifted) or are no longer present (missing).

It does not fix anything. It tells you when to look.

Trigger

Cron 0 */6 * * * on the Pi (defaultHost: "oracle"). Audit JSONs only live there.

Manual surfaces:

• HTTP: POST /api/loom/strands/docs-drift-check/run.
• Loom UI: the manual trigger on the workflow's strand row.

Single step

CHECK (timeout 60s):

1. List ~/.optimalos/transfers/docs-audit/*.json. Recognised filenames are mapped to a default repo root via the REPO_ROOTS table in the workflow file.
2. Walk each JSON, collecting evidence paths. The walker recognises three shapes used across the audits: bare strings ("src/foo.ts:14"), object form ({path: "src/foo.ts", line: 14}), and the where / broadcast_from keys.
3. Strip trailing line/range suffixes (":14", ":14-22").
4. Resolve each path: a repo prefix (optimalOS/, optimal-cli/, dashboard-returnpro/, optimal-docs/) overrides the default root; doc-page paths (returnpro/, cli/, command-center/, etc.) resolve into optimal-docs.
5. stat each resolved path. Mtime newer than the JSON's audited_at → drifted. File missing → missing.

Output

The step returns a DriftResult:

{
  ok: true,
  data: {
    auditsChecked: number,
    pathsTotal: number,
    pathsDrifted: number,
    pathsMissing: number,
    thresholdExceeded: boolean,  // true when drift fraction ≥ 15% OR any file is missing
    byRepo: {
      [auditFilename: string]: {
        total: number,
        drifted: number,
        missing: number,
        topDrifted: string[],   // up to 5, most-recently-modified first
        topMissing: string[]    // up to 5
      }
    }
  },
  note: string  // human-readable summary
}

The threshold for thresholdExceeded lives in the workflow file as THRESHOLD_FRACTION = 0.15. Tune by editing the source.

What it cannot detect

• Prose drift. A claim phrased as "the dashboard refreshes every 2 seconds" can become wrong without any file mtime changing. The check only sees evidence-path mtimes, not whether the prose around them is still accurate.
• Behaviour-level changes. A file modified to refactor without changing meaning still counts as drifted. Expect false positives after large internal refactors; verify with a quick read of the surrounding doc claim before trusting the signal.
• Newly undocumented surfaces. A brand-new feature with no audit-JSON entry is invisible to this workflow. The audit pipeline has to be re-run to bring those into scope.

When the next full audit makes sense

Re-run the four audit agents (the same dispatch that produced the current JSONs) when any of:

• More than ~25% of paths have drifted across two consecutive runs.
• A missing count above 0 for more than one cycle (architectural file moves, not deletions).
• A major shipped feature that lacks any presence in the audit JSONs.

The audit pipeline is described in ~/.optimalos/transfers/docs-audit/work-queue.md on the Pi. It produces fresh JSONs, which become this workflow's new ground truth on the next 6-hour run.

Known gotcha — first-load module cache

OptimalOS's Loom loader busts Bun's module cache on /api/loom/reload via a ?t=<ts> query-string nonce on the dynamic import (optimalOS/src/loom/loader.ts). For edits to existing workflow files this works; for first loads of a brand-new workflow file added while the service is running, the nonce does not appear sufficient — a sudo systemctl restart optimalos.service is required to pick the file up cleanly. After that, in-place edits reload normally.

This affected the rollout of this workflow itself; it does not affect day-to-day operation once a workflow is registered.