--- name: audit-freshness description: Report every resource in this repository whose last-reviewed date has drifted past tolerance, whose targets lag the latest stable Rust release or edition, whose template version pins (rust-toolchain.toml, rust-version, and the crate versions in templates/Cargo.toml) lag the latest stable releases, or whose sources are no longer on the AWESOME-HUMANS.md roster. Use on a periodic cadence or when asked whether the repository is stale, current, or due for a refresh. license: See repository LICENSE compatibility: Requires git; internet access only needed to check latest release versions metadata: repo: awesome-humans/rust change-flow: report-only --- # Audit freshness Report what's stale. This skill never edits content. Version drift goes to `refresh-rust-versions`, and content drift goes to `harvest-sources`. "This repository" in this skill means [awesome-humans/rust](https://github.com/awesome-humans/rust). Run the skill in a checkout, where each path in it, such as `opinions/` or `templates/Cargo.toml`, is relative to the repository's root. ## Tolerances | Check | Tolerance | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | `last-reviewed` on any `opinions/` file | 180 days | | `last-reviewed` after a new edition ships | 60 days from the release | | `targets:` against the latest stable Rust release | Two stable releases, which is 12 weeks. For details, see [Version lag](#version-lag) | | `targets:` against the latest edition | Zero: any lag is a finding | | `last-reviewed` on any commented `templates/` header | 180 days | | `channel` in `rust-toolchain.toml` and `rust-version` in `Cargo.toml` | Checked for shape and for agreement with `targets:`. For details, see [Toolchain pins](#toolchain-pins) | | Crate pins in `templates/Cargo.toml` against crates.io | One minor version, or any major version. Patch-only drift is informational | | The `Versions verified against crates.io … on ` comment in the same file | 90 days, because the pins change faster than the prose | | `research/` topics | 90 days, then reported for `resolve-research`. For details, see [Research](#research) | | `sources:` IDs | For the rules, see [Sources](#sources) | | `Review by YYYY-MM-DD` markings in every tracked file | Zero past the date. Report each for drop-or-re-date triage | | Inbound links to each `opinions/` and `templates/` file | Informational, never a finding. For details, see [Inbound links](#inbound-links) | | References cited in `opinions/` and `templates/` | Zero. For details, see [Cited references](#cited-references) | | `templates/` still implement what `opinions/` require | Zero. For details, see [Templates](#templates) | | `templates/` build, test, and pass Clippy and rustfmt without errors | Zero. For details, see [Templates](#templates) | | Citation and roster URLs resolve | Zero: a dead link is a content finding. Read the latest `Markdown` workflow run, not each URL | ### Version lag Rust ships a stable release every six weeks. Bumping `targets:` in every file each release would bury the content changes in noise, so a file can lag by up to two releases. With 1.101 the latest, `rust-1.99` is fresh and `rust-1.98` is a finding. A release that stabilises something an opinion covers is a finding sooner: report the opinion as soon as the release ships, whatever its lag. ### Toolchain pins The root pins lag by the same two releases as `targets:`. Report these too: - A patch-level pin in the root `rust-toolchain.toml` or `Cargo.toml`, such as `1.99.1`, where the minor release belongs (`refresh-rust-versions`, step 4a). - A template pin that doesn't follow its opinion. - A template's `channel` or `rust-version` whose minor release doesn't match the `targets:` in its header. ### Research Every topic on disk is unresolved, so all of them count. A topic still on disk after promotion is a finding, because promotion ends in deletion. ### Sources - In an opinion or template, every ID must resolve to a Citable row in `AWESOME-HUMANS.md`, or be a reserved `house:` ID. - A `house:` ID is never a finding, in any directory. - In an opinion or template, a watch-list ID or a `**Discovery-only.**` ID is a finding. So is a file whose citable sources are all marked `**Corroborate.**`. `just validate-sources` already fails the build on all three. - `research/` topics can name unvetted sources if the text flags them, but never an opted-out one, because its author asked not to be cited at all. `just validate-sources` doesn't check `research/`, so report an opted-out ID there. ### Cited references A reference is a named crate's or tool's own material, or a repository named under [AWESOME-HUMANS.md: Named references](https://awesome-humans.net/rust/raw/none/AWESOME-HUMANS.md.txt#named-references), linked inline. It supports a reference fact alone, and corroborates a roster-sourced claim. The [admission criteria](https://awesome-humans.net/raw/none/conventions/admission-criteria.md.txt#reserved-ids-markings-and-references) define a reference fact and set the rules. Report each of these as a finding: - **A linked issue or pull request no longer matches the claim.** The opinion calls a feature unstable, or relies on an issue as a current limitation, and the issue has closed, the pull request has merged, or the feature has shipped in a release. A link cited for when a feature shipped, such as a merged stabilization pull request, is current and isn't a finding. Send a feature that has shipped in a stable Rust release to `refresh-rust-versions`, and any other closed issue or merged pull request to `harvest-sources`. - **A reference is the only support for a claim that isn't a reference fact.** The sentence or bullet has no roster citation, and it's a choice, a judgement, or a fact about something other than the reference's subject. The reference is doing a source's job. - **A reference is in `sources:`.** References never go there. - **A reference points into an archived repository, or anchors a line on a branch.** Link where the content moved, and pin a line anchor to a commit. - **A reference is guidance, or publishes a roster source.** Advice, such as a style guide, needs `vet-source`. A repository behind `rust-docs`, such as `rust-lang/reference`, is cited as its published page. To check state, read each linked issue and pull request with `gh` or the web. Report one you couldn't check as "not verified", never as current. ### Inbound links Count what refers to each opinion and template, by link or by file name, from the repository itself: `skills/`, `AGENTS.md`, `agents/`, `HOUSE-OPINIONS.md`, the other opinions, the template comments, and `research/` topics. Leave out the `README.md` Scope bullets and layout tree, because every opinion appears there. Report each file with no inbound links as a pruning candidate. Nothing on the web or in another project shows up here, so a file with no inbound links might still be read. Never report it as stale on that count alone. ### Templates - **Templates match the opinions.** If an opinion names a lint, key, crate, or setting, and its template leaves it out, that's a finding. People copy `templates/`, so a gap ships the advice without the setting. - **Templates build, test, and pass Clippy and rustfmt.** Run `just build-templates`. Templates have no crate of their own, so `cargo` run in `templates/` stops with "the workspace has no members". The recipe copies `templates/` to `target/templates//`, as the default copy and as each house profile's, and adds one member to each with `cargo new --lib crates/example`, which adds itself to `members` and inherits the edition and `[workspace.lints]`. Then it runs `cargo build`, `cargo test`, `CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets`, and `cargo fmt --check`. The `Templates` workflow runs it on every pull request and weekly, so read its latest result on `main` first. Lint and crate compatibility failures show up only this way. The format check covers `rustfmt.toml`: rustfmt exits with an error on a value it can't parse, and only warns about a key it doesn't know or one that needs nightly, so the recipe fails on that warning too. ## Steps 1. **Collect the metadata** from every file under `opinions/` and `research/`, and from the comment headers in `templates/`: `targets`, `last-reviewed`, and `sources`. Count the inbound links to each opinion and template, as [Inbound links](#inbound-links) describes. List every reference the opinions and templates cite, and check each, as [Cited references](#cited-references) describes. 2. **Find the latest released versions** of Rust and the edition, from the same sources as `refresh-rust-versions` step 1. Find the latest stable version of every crate in `templates/Cargo.toml`, with the lookup in `refresh-rust-versions` step 4b. - Read the release announcements between each file's target and the latest release, to find the stabilisations [Version lag](#version-lag) reports early. - If you're offline, skip the checks you can't run, and say so in the report. Report an unchecked pin as "not verified", never as fresh. 3. **Evaluate each resource** against the tolerances. Missing or malformed metadata is a high-severity finding. Then find every `Review by` marking, as [awesome-humans/website: Writing style: Content](https://awesome-humans.net/raw/none/conventions/writing-style.md.txt#content) defines it, with `git grep -nE 'Review by [0-9]{4}-[0-9]{2}-[0-9]{2}'`. It searches every tracked file, so it also finds a marking in a root document, a research topic, or a configuration comment. Skip a line that only quotes or mentions a marking, because it sets no deadline of its own. 4. **Check the roster.** Flag sources in `AWESOME-HUMANS.md` with no _published writing_ in over a year for `vet-source` re-evaluation. Repository activity doesn't count, because opinions don't cite it. 5. **Write the report,** most stale first: - For each resource: the path, the findings, the days or releases over tolerance, and the skill that fixes it. - Counts of fresh, stale, and malformed resources, and the oldest `last-reviewed` date. 6. **Recommend next actions,** usually `refresh-rust-versions`, `harvest-sources`, or `resolve-research` for an overdue topic. Don't run them unless asked. ## Edge cases - **A repository with no opinions yet:** Report that there's nothing to check. Don't pass. - **House content,** which is `house:` in `sources:` and that profile's house blocks or regions, as HOUSE-OPINIONS.md describes: The reserved ID is never an unknown-source finding, and never suggest removing it. `just validate-sources` fails a build where the ID and its blocks don't appear together, or `**House:**` sits outside a block. Review a house block's age with its file, and never count it as stale sourced text. - **Files with no comment header:** A JSON template, because JSON has no comment syntax ([agents/metadata.md](https://awesome-humans.net/rust/raw/none/agents/metadata.md.txt)). None exists today. Missing metadata isn't a finding for one. Audit what it pins against the latest release instead. The root `rust-toolchain.toml` and `Cargo.toml` aren't templates, so they have no header either, and step 4a's pins are their record. - **A crate pinned below the latest release on purpose,** for a known-bad release or a tracked major migration: Report the drift as informational once a comment beside the pin gives the reason. Deliberate staleness must look different from silent staleness. - **A resource that doesn't depend on a version,** such as naming conventions: It can declare `targets: [any]`. Version checks skip it, and review-age checks still apply. - **Clock skew or future dates** in the metadata: Report them as malformed.