task check is not hermetic: docs:artifact:check reads the working tree, so an untracked docs/prds page fails the gate #1697

Closed
opened 2026-10-27 13:41:26 +00:00 by sam · 0 comments
Owner

Symptom: task check fails at docs:artifact:check with 'dev-docs.json is stale' while the committed artifact is correct, and a clean worktree at the same commit passes.

Cause: docsite's check regenerates the artifacts from the Markdown sources in the WORKING TREE, not from git. An untracked docs/prds/*.md therefore makes the committed artifact look stale.

Cost, twice in one session: once for the migration branch, and once when another writer added docs/prds/artifact-sender.md without regenerating. In both cases the obvious reading was 'the artifact is stale' and the actual state was 'there is an untracked page'.

Why it matters beyond the annoyance: task check is the release gate (CI runs it in deploy.yml). A gate whose verdict depends on files that are not in the commit is not reproducible, and the fix it demands (regenerate and commit) is wrong when the page was never meant to be committed.

Evidence: /work/apps/archie-core run at aab8b8d4 -- fails in the shared checkout while an untracked docs/prds/artifact-sender.md exists, passes in a clean worktree at the same sha.

Options: enumerate pages via git ls-files rather than a directory walk; or fail with a message that names an untracked source page rather than reporting drift.

Close reason

Resolved by 4f71c81b: docsite enumerated tracked/indexed sources instead of untracked pages. Subsequently 15e55c1c removed docsite; current task check has no docs artifact check. The reported untracked-page failure path no longer exists.


Imported from beads archie-core-zhjj · GitHub #1093 · type bug · priority P2 · created 2026-09-22 · closed 2026-10-04

Symptom: `task check` fails at docs:artifact:check with 'dev-docs.json is stale' while the committed artifact is correct, and a clean worktree at the same commit passes. Cause: docsite's check regenerates the artifacts from the Markdown sources in the WORKING TREE, not from git. An untracked `docs/prds/*.md` therefore makes the committed artifact look stale. Cost, twice in one session: once for the migration branch, and once when another writer added docs/prds/artifact-sender.md without regenerating. In both cases the obvious reading was 'the artifact is stale' and the actual state was 'there is an untracked page'. Why it matters beyond the annoyance: `task check` is the release gate (CI runs it in deploy.yml). A gate whose verdict depends on files that are not in the commit is not reproducible, and the fix it demands (regenerate and commit) is wrong when the page was never meant to be committed. Evidence: /work/apps/archie-core run at aab8b8d4 -- fails in the shared checkout while an untracked docs/prds/artifact-sender.md exists, passes in a clean worktree at the same sha. Options: enumerate pages via `git ls-files` rather than a directory walk; or fail with a message that names an untracked source page rather than reporting drift. ### Close reason Resolved by 4f71c81b: docsite enumerated tracked/indexed sources instead of untracked pages. Subsequently 15e55c1c removed docsite; current task check has no docs artifact check. The reported untracked-page failure path no longer exists. --- _Imported from beads `archie-core-zhjj` · GitHub #1093 · type bug · priority P2 · created 2026-09-22 · closed 2026-10-04_
sam added the bugmedium labels 2026-10-27 13:41:26 +00:00
sam self-assigned this 2026-10-27 13:41:26 +00:00
sam closed this issue 2026-10-27 13:41:26 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#1697