# CI gate: PROJECT_STRUCTURE.md freshness (https://jackin.tailrocks.com/roadmap/ci-project-structure-gate/)



**Status**: Partially implemented — docs CI already checks roadmap sidebar coverage and source repository links; remaining work is an actual Rust module-map freshness assertion for <RepoFile path="PROJECT_STRUCTURE.md">PROJECT\_STRUCTURE.md</RepoFile>

## Current shape [#current-shape]

<RepoFile path="PROJECT_STRUCTURE.md">PROJECT\_STRUCTURE.md</RepoFile> is now a root orientation map that delegates detailed source navigation to the [Codebase Map](/reference/getting-oriented/codebase-map/). The docs workflow already runs `cargo xtask docs repo-links` and `cargo xtask roadmap audit`, so published docs routes and roadmap sidebar coverage are gated.

What is still missing is a repository-level assertion that newly added Rust module files are either represented in the root structure map or intentionally covered by the Codebase Map.

## Remaining assertion [#remaining-assertion]

Add a lightweight CI check that compares new `.rs` module files in the PR against the documented source map. The check should:

* use the PR diff, not the whole historical tree;
* ignore `tests.rs`, generated code, and crate-internal child modules that are intentionally covered by a parent entry;
* fail only when a new top-level module surface lacks any matching entry in <RepoFile path="PROJECT_STRUCTURE.md">PROJECT\_STRUCTURE.md</RepoFile> or the [Codebase Map](/reference/getting-oriented/codebase-map/);
* run after checkout has enough base history to compute the diff reliably.

## Caveats [#caveats]

A naive basename grep produces false positives and false negatives after the workspace split because many real module roots now live under `crates/*/src/<module>.rs` and Rust 2024 self-named modules deliberately avoid `mod.rs`. Prefer a small script with explicit ignore rules over inline YAML shell.