loop-docs-freshness

name	loop-docs-freshness
description	Weekly loop that checks the public API docs (docs.accounted.se) against what this repo generates today, files one deduped drift issue, and proposes the re-export PR in the gnubok-website repo. Use on a weekly cadence or on-demand via /loop-docs-freshness. Follows .claude/loops.md (propose-don't-merge).

loop-docs-freshness

Goal: what docs.accounted.se serves is byte-identical to what this repo would generate today. The docs site lives in the separate jakobwennberg/gnubok-website repo and is fed by manual snapshot exports, so it silently drifts whenever an endpoint, error code, or content page changes here. Never merge. Read .claude/loops.md first.

Preflight

gh auth status, repo erp-mafia/accounted. If it fails, stop and report "environment not provisioned".

1. Due check (weekly semantics)

Find the most recent trace: gh issue list --label loop:docs --state all --limit 5 --json number,title,updatedAt plus the newest <!-- loop-docs-freshness-run: YYYY-MM-DD --> marker in those issues' comments. If a run marker is dated less than 6 days ago, report "not due" and stop, unless the user invoked /loop-docs-freshness explicitly (explicit invocation always runs).

2. Run the deterministic check

From an up-to-date main checkout (the comparison is "what main generates" vs "what the site serves"; a feature branch would produce false drift):

npx tsx scripts/check-docs-freshness.mts

• Exit 0 (in sync): if an open loop:docs drift issue exists, comment that the site is back in sync and close it. Post the run marker (step 5). Done.
• Exit 2 (fetch/build failure): the site is unreachable or the content modules changed shape. Do NOT file a drift issue. If this is the second consecutive exit-2 run, file/update one issue labeled loop:auto, loop:docs, loop:needs-human describing the failure. Stop.
• Exit 1 (drift/missing): continue.

3. File or update ONE drift issue (cap: 1 per run)

The script prints a FINGERPRINT per drifted page. Compute the run fingerprint = first 12 hex chars of sha256 over the sorted page fingerprints, then dedupe per .claude/loops.md:

• gh issue list --search "<run-fingerprint> in:body" --state all : match open → comment the fresh script summary instead of filing; match closed → reopen with a note.
• Otherwise file one issue (never one per page):
  • Title: docs drift: docs.accounted.se out of sync (<N> pages)
  • Body: the script's non-ok output verbatim, the remediation steps below, and <!-- loop-fingerprint: <run-fingerprint> -->.
  • Labels: loop:auto, loop:docs, documentation.

If an older open loop:docs issue has a different fingerprint (the drift changed), comment on it with a pointer to the new issue and close it: one open drift issue at a time.

4. Propose the fix (cap: 1 website PR per run)

Two failure classes, two remedies:

• Generated snapshots stale (reference*, errors.md, connect-claude.md): run npx tsx scripts/export-docs-to-website.mts. It writes *.generated.ts into ~/gnubok-website.
• Hand-copied pages stale (changelog.md, versioning.md, webhooks.md, cookbook/*): copy the exported markdown constants from lib/docs/content/ in erp-base over the website repo's duplicates in lib/docs/content/. Mechanical copy only; if the two sides have diverged in structure (not just content), escalate with loop:needs-human instead.

The ~/gnubok-website checkout is often on a human's WIP branch. Never commit on it. Work in a fresh worktree from origin/main:

git -C ~/gnubok-website fetch origin
git -C ~/gnubok-website worktree add /tmp/loop-docs-freshness-wt -b loop/docs-freshness-<run-fingerprint> origin/main

Re-run the export/copy against the worktree, commit, push, and open a PR in jakobwennberg/gnubok-website whose body links the erp-base drift issue and embeds the same fingerprint marker. Then remove the worktree. Never merge; the founder deploys the website.

404s on pages whose routes exist on the website's origin/main (seen 2026-08-09 for every reference/<slug>.md and cookbook/<slug>.md mirror) are a deploy/runtime problem, not a snapshot problem: a re-export PR will not fix them. Label the issue loop:needs-human and say so explicitly.

5. Run marker + report

Comment <!-- loop-docs-freshness-run: YYYY-MM-DD --> plus a one-line summary on the drift issue touched this run (or, when in sync and nothing is open, skip the marker comment and rely on the closed issue's timestamp). Summarize: pages in sync / drifted / missing, issue filed or updated, website PR opened, escalations. That summary is the completion notification.

Anti-thrash

If a previous run already opened a website PR for the same run fingerprint and it is still open, do not open another: comment on the existing PR/issue instead. If the same fingerprint drifts again after its PR merged and deployed, something upstream regenerates differently: loop:needs-human.