amirfish1 / docs-drift

Docs-drift spawns a single fresh CCC session that treats a doc as a list of
factual assertions about the code and checks each one against the source. It
does not follow the docs as a user would — it enumerates the claims (this
endpoint exists, this flag is --foo, this response has field bar, this
default is 127.0.0.1, this version is X.Y.Z) and greps/reads the code to
confirm or refute each. The output is a drift ledger. It builds on the
spawn/report_to mechanics in the ccc-orchestration skill — read that first for
the full Spawn/Inject/Ask API.

Cost

1 spawned session. Each spawn is a real billed session on the user's
kanban — tell the user the count before spawning. Point it at a bounded set
of docs (one file, or a section) — "audit all the docs" is a fleet job
(fleet-lane-dispatch with a per-doc brief), not one session.

Setup

CCC_URL="$(cat ~/.claude/command-center/port.txt 2>/dev/null || echo "${CCC_URL:-http://127.0.0.1:8090}")"
curl -sf --max-time 2 "$CCC_URL/api/version" >/dev/null 2>&1 || CCC_URL="http://127.0.0.1:8090"
curl -sf --max-time 2 "$CCC_URL/api/version" >/dev/null 2>&1 || CCC_DOWN=1

• (a) Run every CCC curl with the network sandbox disabled — the Bash
  sandbox blocks loopback and fails spuriously even when CCC is up.

• (b) URL-encode repo_path in query strings (+ → %2B, space → %20).

• (c) Resolve your own session id: $CLAUDE_SESSION_ID, else the newest
  *.jsonl under ~/.claude/projects/<slugified-cwd>/ (see ccc-orchestration).

Preconditions — decide these BEFORE spawning

• (a) The exact doc(s) to audit — file paths or a named section. One file or
  one section per run; the more bounded, the sharper the ledger.

• (b) The source of truth — which code the claims should match (a module, a
  set of endpoints, a config schema). If you don't tell it where the truth
  lives, it wastes the run hunting.

• (c) The claim types that matter for this doc — API response fields, CLI
  flags, endpoint paths, config keys/defaults, file paths, version strings,
  copy-paste example commands. Naming them focuses the extraction.

Spawning the auditor

curl -s -X POST "$CCC_URL/api/sessions/spawn" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "prompt": "Audit this doc for drift against the code. DOC: <path or section>. SOURCE OF TRUTH: <module / endpoints / config to check against>. Method: 1) Extract EVERY checkable factual claim the doc makes about the code — endpoint paths, request/response field names, CLI flags, config keys and their stated defaults, file paths, version strings, and any copy-paste example command. Ignore prose, motivation, and opinion; only claims a reader could act on and be wrong. 2) For EACH claim, verify it against the actual code (grep / read the source — do NOT trust the doc). 3) Classify each: MATCH (doc agrees with code), DRIFT (doc contradicts code — wrong field name, renamed flag, changed default, dead endpoint, stale version), or UNVERIFIABLE (could not locate the truth — say why). Report ONLY the DRIFT and UNVERIFIABLE rows as a ledger; give a MATCH count as one summary number. Each drift row: the exact doc quote + line, what the code actually says (with file:line evidence), severity (BROKEN = a reader following this will fail, e.g. dead endpoint or wrong flag / MISLEADING = works but the doc is wrong, e.g. stale default / COSMETIC = typo-level), and the one-line doc patch. Finish with a verdict: is this doc safe to trust as-is, yes or no?",
  "repo_path": "/abs/path/to/repo",
  "report_to": "<your-session-id>"
}
JSON

Omit "model" and "reasoning_effort": the server spawn defaults (Settings →
Spawn defaults) apply. Pass either explicitly to keep cost down, with
"engine" alongside it, since both are validated per engine (see
ccc-orchestration § 2 for the per-engine effort ladders). CCC appends the
return-address footer (report_to), so the auditor injects its ledger back to
you when it finishes.

Waiting for the report

After spawning, end your turn. Tell the user an auditor is checking the doc
against the code and give its session id. The ledger arrives by injection
(report_to) — do not poll or sleep-loop. If it never arrives, check
GET /api/sessions/spawned for whether the child is still alive.

When the report arrives

Turn the ledger into doc fixes:

• BROKEN drift is a doc bug that will actively mislead — fix before the next
  reader hits it (a dead /api/* endpoint, a renamed flag, a wrong required
  field). For a public repo these ship the moment you push, so treat them like
  code bugs.

• MISLEADING — the reader gets through but on wrong information (a stale
  default, an old version string); correct the wording.

• COSMETIC — polish when convenient.

• UNVERIFIABLE rows are their own signal — either the doc is describing
  something that no longer exists, or the truth moved; investigate each.

Dry run

If the arguments contain dry-run, print the exact payload — session count (1),
the full auditor prompt with the doc path and source-of-truth filled in, and the
target repo — and POST nothing.

When CCC is down

If CCC_DOWN=1 or the spawn curl returns connection refused (exit 7), fall back
to the built-in Task tool subagent with the same claim-extraction prompt —
fresh context matters less here than for dogfood, because the value is the
systematic cross-check, not naïve eyes. You lose only kanban visibility. Never
pretend the CCC spawn ran.

What this is not

• Not dogfood — that follows the getting-started path as a user and reports
  where it stumbles; it only catches drift on the exact steps it walks.
  Docs-drift ignores the experience and checks every claim in the doc against the
  code, including claims off the happy path. Run dogfood to prove the
  quickstart works; run docs-drift to prove a reference doc is not lying.

• Not /code-review — that judges whether the code is right. This assumes the
  code is the truth and judges whether the doc still matches it.