release: 0.5.0 — release-prep audit, generated Copilot instructions, hermetic-auth hint

[MarkusNeusinger]

What

Release prep for 0.5.0 plus the pre-release audit of everything that landed since 0.4.0 (docs, skills, rules, the 15-item 2026-07 audit backlog), and one fix the audit's own live testing turned up.

The release itself

• __version__ 0.4.0 → 0.5.0 (minor — features and a diagnostics fix, no breaking change).
• CHANGELOG: ## [Unreleased] re-dated to ## [0.5.0] - 2026-07-25, a fresh empty [Unreleased] above it, compare-link row added. The section had accumulated two ### Added blocks around one ### Changed (an artifact of prepending each feature) — merged into one Added + one Changed, plus a new ### Fixed. No wording changed. There was no flip-gate blockquote to carry.
• 0.5.0 carries the whole 2026-07 audit backlog Agentic direct-edit ingest, strict validators, contradiction handling & interactive viewer #1–Harden wiki rollback against undeletable dirs on network shares #15, now all shipped: BM25 search, cost accounting, audio + PDF text pre-passes, MCP prompts/resources, the capture bridge, hermetic sessions, resumable chunked ingest, the page cache, ingest --jobs N, serve --http, and citadel refresh.

What the audit found and this PR fixes

• .github/copilot-instructions.md was 105 lines behind the file it claims to mirror: it still advertised 12 MCP tools (there are 13) and knew nothing of citadel refresh, citadel capture, ingest --jobs, serve --http, the ContextVar wiki accessors, or the HERMETIC/HTTP_*/JOBS knobs. The reviewer bot in this repo's own ship path was reviewing against a stale contract. A prose "keep the two in sync" promise had not survived four feature PRs — so it is now mechanical: the Copilot file is CLAUDE.md with a swapped header and re-rooted relative links, regenerated with CITADEL_WRITE_COPILOT_DOC=1 and pinned by a drift guard next to the existing env-knob and README-link guards in tests/test_packaging.py. This is the one refactor the audit judged worth doing now: it removes a 370-line hand-maintained duplicate rather than adding anything.
• README never mentioned ingest --jobs — a headline feature of this release. Added, with the default-1 cross-linking trade-off stated.
• docs/audit-2026-07.md: the § 1.4 coverage table was split by a resolution note inserted between its rows, so two rows rendered as literal text; § 1.1 still called refresh unreleased; the accepted-trade-off list still claimed "no offline PDF reader" after backlog Make abbreviations first-class: type, generated glossary, lint nudge #10 shipped one.
• llm.py: an auth-shaped session failure on a hermetic run now names the knob that caused it. Found by live-testing ingest --jobs for this release: inside a container whose claude credentials live in user-level settings, all four sources failed identically with "Authentication error · This may be a temporary network issue, please try again" — because hermetic mode's --bare skips exactly those settings. The message points at the network; nothing mentioned CITADEL_HERMETIC. Auth-shaped failures raised from a run that really passed an isolation flag (read off the argv, so the probe-gated "nothing was passed" case is untouched, and quota/timeout failures are unaffected) now carry a one-line hint naming CITADEL_HERMETIC=0, with a symptom→fix entry in docs/troubleshooting.md and a pointer from the configuration.md row.

Deliberately not in this PR (reported, not silently done): a citadel/ingest.py split (3036 lines vs. 1075 for the next-largest module) — a wide mechanical move through the most load-bearing module days before a tag; it belongs in its own post-release PR routed through verify-corpus.

Testing

Offline gates:

• uv run pytest -q — 1221 passed, 1 skipped (1218 before; +1 drift guard, +2 hermetic-hint tests)
• uv run ruff check . — All checks passed!
• uv run ruff format --check . — 93 files already formatted
• CITADEL_WORKSPACE=corpora/beverages uv run python -m citadel lint — OK; all nine committed showcase wikis lint OK
• uv run python -m citadel --version → citadel 0.5.0

Live runs (real claude sessions on haiku, in throwaway sandboxes — the llm.py diff means the routing table asks for a corpus run, and parallel ingest wanted proving under real contention):

• Maximum-overlap corpus — 4 sources all describing one object, --jobs 4. Forced the collision path hard: 3 of 4 sources raced and were re-run serially (4 parallel + 3 serial = 7 sessions, 277 s, $0.93). Result: check and lint both exit 0 with every counter zero, one merged page citing all four sources, and every source's unique facts intact across three consecutive re-runs (1.85 kg + 340 m tether; 210 m + 46 messages; 40-flight-hour interval + 70 kg retirement; 1874 design + 1881 handover). Nothing was overwritten by a later promote — "re-run serially, then merge into the winner's page" holds under a 3-way collision, not just a 2-way one. Cross-linking still produced separate linked persons/, organizations/, and misc/ pages with zero orphans.
• beverages, 14 sources, --jobs 4 — all 14 first-pass sessions completed with zero races (the realistic case: topically related sources still mostly land on different pages), then the harness reaped the runner mid-re-run. That accident tested the all-or-nothing guarantee for free: the live wiki came out check exit 0, 0 broken links, 0 orphans, 0 fabricated sources, 7 sources durably recorded in the manifest and 7 cleanly back to pending — nothing half-ingested, with the stale lock and staging dir left exactly as the next run's reclaim logic expects. A resumed run over only the un-promoted sources is what confirms the recovery path.

One thing a human should weigh before tagging (needs live agent sessions): all nine showcase wikis are stamped rules_version=ac0a1175f9da while the current rulebook is c99fc290864f — the audio + PDF work changed formats/pdf.md, added formats/transcripts.md, and touched core.md/schema.md after the last corpus rebuild. CI flags this as advisory only. gazette is the corpus whose ingest path materially changed (agent-native PDF read → pypdf text pre-pass), so a verify-corpus gazette run is the highest-value pre-tag check.

🤖 Generated with Claude Code

https://claude.ai/code/session_01B2VCXZmg8g4nFucS5oZiz9

[Copilot]

Pull request overview

Prepares the 0.5.0 release by bumping the package version, finalizing the changelog/audit documentation, and making Copilot instructions mechanically derived from CLAUDE.md to prevent drift between the two agent-guidance documents.

Changes:

• Bump cite-citadel to 0.5.0 and finalize the 0.5.0 changelog section + compare links.
• Add a drift guard test to ensure .github/copilot-instructions.md is a deterministic derivation of CLAUDE.md (with an opt-in regeneration path).
• Update docs to reflect shipped features (ingest --jobs, refresh, offline PDF text extraction note) and fix audit table rendering.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_packaging.py	Adds deterministic generator + test drift guard for Copilot instructions; supports opt-in regeneration via env var.
README.md	Documents citadel ingest --jobs N and its cross-linking tradeoff, linking to recipes.
docs/audit-2026-07.md	Marks refresh as released, fixes the “offline PDF reader” note, and repairs the coverage table formatting.
CLAUDE.md	Documents that .github/copilot-instructions.md is generated and how to regenerate it.
citadel/__init__.py	Bumps __version__ from 0.4.0 to 0.5.0.
CHANGELOG.md	Finalizes 0.5.0 section (date + structure) and updates compare links.
.github/copilot-instructions.md	Updates to the regenerated, current CLAUDE-derived guidance content and header.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.