Agent metadata drift: stale Project-status date, missing edition-2024/workspace-lints milestone, wrong buildutil description

[chbaker0]

Filed by an AI coding agent (Claude Code).

Periodic audit of the repo's agent-facing metadata (AGENTS.md, CLAUDE.md, .claude/**) against actual project state. Anchor = most recent metadata-touching commit 7761ef0 ("CI: gate clippy over every workspace package", 2026-07-23); everything up to HEAD (c8994d9) was in scope. This continues the trail of prior audits (#27, #34) — those findings are now fixed; these are new.

Drift found (in-scope metadata)

1. Stale "Last updated" date. AGENTS.md's Project status opens with Last updated 2026-07-21, but the file has been edited several times since — most recently the anchor commit 7761ef0 on 2026-07-23 (clippy-gating rewrite) and f16c8ef ("Fix metadata drift…"). The date was never bumped alongside those edits.

2. Project status omits the two biggest structural changes since it was written. Between the 2026-07-21 status and now, the workspace was migrated to Rust edition 2024 (674612d, PR Migrate all crates to Rust edition 2024 #33) and its unsafe/safety lints were centralized in [workspace.lints] (511f0b7, PR Centralize unsafe lints via workspace [lints] #36; safety clippy lints promoted to deny in PR Promote clippy safety lints to deny #45). The status narrative still peaks at "just finished migrating from Multiboot2/GRUB to UEFI" and never mentions the edition/lints work, even though Cargo.toml now carries edition = "2024" and [workspace.lints.rust]/[workspace.lints.clippy]. An onboarding agent gets an outdated sense of where the project is. (The clippy CI gate paragraph is accurate — only the high-level milestone framing is stale.)

3. buildutil description is inaccurate. AGENTS.md calls it "helpers shared between build scripts and mkimage." In reality buildutil is depended on only by mkimage (per Cargo.toml and a source grep — the only .rs reference is mkimage/src/main.rs); the live make-image.sh build path is pure shell + cargo and never touches it. Since mkimage is itself flagged as a dead pre-UEFI leftover, buildutil effectively only feeds dead code — the "build scripts" framing overstates its live role.

Verified accurate (no change needed): the kernel_entry/kernel_main behavior described in Project status matches src/kmain.rs; the cargo-alias table matches .cargo/config.toml; src/qemu.rs and the CI/QEMU-boot descriptions match .github/workflows/ci.yml; the .claude/ agent + qemu-boot skill are consistent with AGENTS.md.

Breadcrumbs (flagged, not fixed in the metadata PR)

• AGENTS.md defers to a stale README. AGENTS.md line 3 says "See README.md for the package layout and cargo alias reference," but README.md is itself out of date: it claims make-image.sh "fetches OVMF prebuilts" into target/ovmf and shows TESTOS_QEMU_EFI_CODE=target/ovmf/… defaults, whereas OVMF is now vendored hermetically under third_party/ovmf and nothing is fetched at build time. README is out of the metadata audit's scope, but the deferral compounds the drift — worth a separate README refresh (or trimming the deferral).
• Dead multiboot2 dependency. The kernel's Cargo.toml still declares multiboot2 = …, but nothing in the tree uses it (no .rs reference) — a pre-UEFI leftover that could be dropped. Code cleanup, not metadata.

Fragile/manual workflows that map to a skill or tool

• This audit itself is a recurring manual chore (metadata ↔ codebase reconciliation).
• The "full PR flow" convention in AGENTS.md — push → open PR → detect squash-vs-merge-commit convention by inspecting a recent merge commit's parents → merge with the matching flag → switch to master → fast-forward → delete local+remote branch → git fetch --prune — is encoded as brittle prose that each agent re-derives.

External tooling that could close these gaps

Each candidate below was confirmed listed on an Anthropic property and checked for recent activity (searches delegated to subagents).

• CLAUDE.md Management Plugin — https://claude.com/plugins/claude-md-management (source: anthropics/claude-plugins-official). Purpose-built for exactly the doc-drift gap: a claude-md-improver skill that audits CLAUDE.md/AGENTS.md-style memory files against the current codebase and emits a scored gap report with fixes, plus /revise-claude-md to capture end-of-session learnings. Anthropic-authored; added 2026-01-16, commits through 2026-02-20. Strongest fit for making this recurring audit less manual.
• commit-commands plugin (Anthropic official, anthropics/claude-plugins-official, v1.0.0). Ships /commit, /commit-push-pr (branch→commit→push→PR), and /clean_gone (prune [gone] branches) — covers the push→PR→cleanup ends of the "full flow." It does not detect squash-vs-merge convention or fast-forward master, so the middle stays bespoke; the realistic path is a small project-local .claude/skills/ skill that wraps these primitives + the convention-detection heuristic (backed by the already-connected GitHub MCP server).
• rust-analyzer-lsp plugin — https://claude.com/plugins/rust-analyzer-lsp. Real-time diagnostics/clippy for the interactive edit loop. Already tracked in Tooling: rust-analyzer-lsp plugin for faster nightly-drift diagnosis #42 — cross-referenced here, not re-filed. (Miri/-Zbuild-std/QEMU-boot verification correctly stays bespoke; no off-the-shelf Anthropic tooling reaches that far, consistent with the existing qemu-boot project skill.)
• (For completeness: claude-code-action for unattended CI triage is already tracked in Tooling: claude-code-action to auto-triage the daily scheduled Miri run #43.)

Suggested fix

A draft PR corrects drift items 1–3 in AGENTS.md only (no code changes). The breadcrumbs and tooling adoption above are left as follow-ups.

[chbaker0]

Consolidated: all drift corrections from the daily-routine issues were folded into PR #52 (merge pending). The routine's duplicate-filing behavior itself is now tracked as #55.