<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/reference/terminology-exemptions/">
  <id>https://docs.spec-kitty.ai/development/reference/terminology-exemptions/</id>
  <title>Terminology Guard Exemption Policy</title>
  <updated>2026-11-12T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/reference/terminology-exemptions/"/>
  <summary>Policy for the six surfaces exempt from spec-kitty terminology guards: ADRs, migrations, archived pages, archival plans, dated reports and the Unreleased-only CHANGELOG scan.</summary>
  <content type="html">&lt;span id=&quot;terminology-guard-exemption-policy&quot;&gt;&lt;/span&gt;
&lt;p&gt;This document describes the surfaces deliberately excluded from the two active
terminology drift guards:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_terminology_guards.py&lt;/code&gt; — live-doc scan for deprecated CLI
option names and removed command patterns&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_legacy_terminology.py&lt;/code&gt; — repo-wide scan for
specific forbidden legacy terms&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These exclusions are &lt;strong&gt;intentional policy decisions&lt;/strong&gt;, not workarounds. The
rationale for each exempt surface is recorded here so future contributors can
distinguish “this surface is correctly out of scope” from “this surface was
accidentally missed.”&lt;/p&gt;
&lt;h2 id=&quot;background&quot;&gt;Background&lt;/h2&gt;
&lt;p&gt;The terminology guards enforce that active, first-party surfaces — source code,
doctrine skills, and live documentation — stay aligned with the canonical
vocabulary. They scan live surfaces only; surfaces that are historical records or
archival snapshots are deliberately out of scope.&lt;/p&gt;
&lt;p&gt;Six categories of surfaces are currently exempt from the live-doc component of
the guards. Each is described below.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;exempt-surface-1-docsadr--immutable-architectural-decision-records&quot;&gt;Exempt Surface 1: &lt;code dir=&quot;auto&quot;&gt;docs/adr/&lt;/code&gt; — Immutable Architectural Decision Records&lt;/h2&gt;
&lt;h3 id=&quot;what-is-excluded&quot;&gt;What is excluded&lt;/h3&gt;
&lt;p&gt;All files under &lt;code dir=&quot;auto&quot;&gt;docs/adr/&lt;/code&gt; are excluded from:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the live-doc scan in &lt;code dir=&quot;auto&quot;&gt;_live_doc_scan_targets()&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_terminology_guards.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;the legacy-term scan &lt;code dir=&quot;auto&quot;&gt;_EXCLUDED_PATH_FRAGMENTS&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_legacy_terminology.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;why-it-is-exempt&quot;&gt;Why it is exempt&lt;/h3&gt;
&lt;p&gt;Architectural Decision Records (ADRs) are immutable, byte-invariant snapshots by
convention (NFR-001/C-002/C-006). An ADR records the reasoning behind a decision
at a specific point in time. Once an ADR is written, its body is never modified —
even if the vocabulary it uses has since been superseded. Retroactively altering
an ADR body would corrupt the historical record and undermine the purpose of
decision documentation.&lt;/p&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;docs/adr/&lt;/code&gt; tree was relocated from &lt;code dir=&quot;auto&quot;&gt;architecture/&lt;/code&gt; (which was already
outside the scan perimeter) into &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; during the Common Docs consolidation
(mission doc-quality-hardening). The exemption was carried over so that the
relocation did not introduce spurious guard failures on files that are
intentionally historical.&lt;/p&gt;
&lt;h3 id=&quot;scope-boundary&quot;&gt;Scope boundary&lt;/h3&gt;
&lt;p&gt;The exemption is narrow: only &lt;code dir=&quot;auto&quot;&gt;docs/adr/&lt;/code&gt;. All other pages under &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; remain
scanned. This narrowness is pinned by &lt;code dir=&quot;auto&quot;&gt;test_docs_adr_exemption_is_narrow&lt;/code&gt; in both
guard files, which confirms that live docs pages outside the exempt roots are
still being scanned.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;exempt-surface-2-unreleased-only-changelog-scan&quot;&gt;Exempt Surface 2: Unreleased-Only CHANGELOG Scan&lt;/h2&gt;
&lt;h3 id=&quot;what-is-excluded-1&quot;&gt;What is excluded&lt;/h3&gt;
&lt;p&gt;Both &lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt; (at the repository root) and &lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt;
are scanned, but &lt;strong&gt;only the unreleased section&lt;/strong&gt; — the portion of the file above
the first versioned heading — is checked for terminology drift. Historical version
sections are not scanned.&lt;/p&gt;
&lt;h3 id=&quot;why-it-is-exempt-1&quot;&gt;Why it is exempt&lt;/h3&gt;
&lt;p&gt;A CHANGELOG is an append-at-the-top log. Each released version section records
what changed at the time of that release, using vocabulary that was canonical at
that time. Rewriting historical version sections to conform to vocabulary that
became canonical later would make the CHANGELOG historically inaccurate.&lt;/p&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;Unreleased&lt;/code&gt; section, by contrast, describes work that has not yet shipped
and must reflect current canonical vocabulary.&lt;/p&gt;
&lt;h3 id=&quot;how-it-is-implemented&quot;&gt;How it is implemented&lt;/h3&gt;
&lt;p&gt;The guard implements this boundary via &lt;code dir=&quot;auto&quot;&gt;_extract_changelog_unreleased()&lt;/code&gt;, which
returns only the content above the first &lt;code dir=&quot;auto&quot;&gt;## [X.Y.Z]&lt;/code&gt; heading. Both CHANGELOG
files are explicitly excluded from the &lt;code dir=&quot;auto&quot;&gt;docs/**/*.md&lt;/code&gt; glob and processed
separately through this extractor, ensuring only the unreleased content is
evaluated.&lt;/p&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;docs/changelog/README.md&lt;/code&gt; index page is not a CHANGELOG file and is still
scanned as a normal live doc.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;exempt-surface-3-archived-sub-areas-under-docsplans&quot;&gt;Exempt Surface 3: Archived Sub-areas Under &lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt;&lt;/h2&gt;
&lt;h3 id=&quot;what-is-excluded-2&quot;&gt;What is excluded&lt;/h3&gt;
&lt;p&gt;Two subdirectories under &lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt; are excluded from the live-doc scan:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/plans/engineering-notes/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/plans/initiatives/&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;why-it-is-exempt-2&quot;&gt;Why it is exempt&lt;/h3&gt;
&lt;p&gt;These subdirectories contain archival records relocated from the previously
unscanned &lt;code dir=&quot;auto&quot;&gt;architecture/&lt;/code&gt; tree during the Common Docs consolidation. Their
content consists of:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;engineering-notes/&lt;/code&gt; — retained deep-dive notes from earlier development eras&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;initiatives/&lt;/code&gt; — completed initiative records describing work that has already
concluded&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;notes/&lt;/code&gt; — informal engineering notes from previous development cycles&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;All three are archival: they document decisions, investigations, and completed
work. Their content uses vocabulary that was current at the time of writing and
is not maintained going forward. Scanning them would produce false positives that
cannot be remediated without rewriting historical context — the same reasoning
that exempts &lt;code dir=&quot;auto&quot;&gt;docs/adr/&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;scope-boundary-1&quot;&gt;Scope boundary&lt;/h3&gt;
&lt;p&gt;Only the three named subdirectories are exempt. The &lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt; root and all
non-archival pages at the top level of &lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt; remain live surfaces that
are fully scanned.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;exempt-surface-4-docsmigrations--migration-runbooks&quot;&gt;Exempt Surface 4: &lt;code dir=&quot;auto&quot;&gt;docs/migrations/&lt;/code&gt; — Migration Runbooks&lt;/h2&gt;
&lt;h3 id=&quot;what-is-excluded-3&quot;&gt;What is excluded&lt;/h3&gt;
&lt;p&gt;All files under &lt;code dir=&quot;auto&quot;&gt;docs/migrations/&lt;/code&gt; are excluded from the live-doc scan.&lt;/p&gt;
&lt;h3 id=&quot;why-it-is-exempt-3&quot;&gt;Why it is exempt&lt;/h3&gt;
&lt;p&gt;Migration runbooks must &lt;em&gt;name&lt;/em&gt; the deprecated flags, commands, and workflows they
help users move away from — &lt;code dir=&quot;auto&quot;&gt;--feature&lt;/code&gt;, the pre-3.0 main-centric workflow, legacy
env vars, and so on. The whole purpose of a migration doc is to reference the old
vocabulary verbatim so a reader can find-and-replace it. Scanning these pages
would flag the very terms they exist to document, producing false positives that
cannot be remediated without defeating the doc’s purpose. Same reasoning as
&lt;code dir=&quot;auto&quot;&gt;docs/adr/&lt;/code&gt;: the content legitimately carries era-correct vocabulary.&lt;/p&gt;
&lt;h3 id=&quot;scope-boundary-2&quot;&gt;Scope boundary&lt;/h3&gt;
&lt;p&gt;Only &lt;code dir=&quot;auto&quot;&gt;docs/migrations/&lt;/code&gt; is exempt. All other live &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; pages remain fully
scanned.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;exempt-surface-5-docsreports--dated-point-in-time-report-snapshots&quot;&gt;Exempt Surface 5: &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; — Dated Point-in-Time Report Snapshots&lt;/h2&gt;
&lt;h3 id=&quot;what-is-excluded-4&quot;&gt;What is excluded&lt;/h3&gt;
&lt;p&gt;All files under &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; are excluded from:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the live-doc scan in &lt;code dir=&quot;auto&quot;&gt;_live_doc_scan_targets()&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_terminology_guards.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;FORBIDDEN_SCAN_ROOTS&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;the non-canonical decision-command-shape scan in
&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/test_decision_command_shape_consistency.py&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;REPORT_SNAPSHOT_PREFIX&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;the retired doctrine-profile-directory path scan in
&lt;code dir=&quot;auto&quot;&gt;tests/audit/test_no_legacy_agent_profiles_path.py&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;_SNAPSHOT_EXCLUDED_DIRS&lt;/code&gt;; #5474)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;why-it-is-exempt-4&quot;&gt;Why it is exempt&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; holds dated, point-in-time report snapshots — for example
&lt;code dir=&quot;auto&quot;&gt;docs/reports/tracer-friction-recon/2026-09-26/&lt;/code&gt;, a recon report generated on
2026-09-26 that describes, as part of its findings, retired command/flag
shapes (the removed &lt;code dir=&quot;auto&quot;&gt;--feature&lt;/code&gt; alias; non-canonical decision-subcommand
phrasing) exactly as they existed in the surfaces it was investigating.
Rewording those quotations to match current vocabulary would falsify the
report: the whole value of a dated snapshot is that it records what was true
on the date it was taken, not what is true today. This is the same rationale
as the &lt;code dir=&quot;auto&quot;&gt;docs/adr/&lt;/code&gt; exemption above.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; is already classified as an immutable-historical-snapshot
prefix by &lt;code dir=&quot;auto&quot;&gt;ARCHIVE_PATH_PREFIXES&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_dead_src_path_literals.py&lt;/code&gt;; this exemption
mirrors that existing classification rather than inventing a third,
divergent list of “which report/archive paths are historical.”&lt;/p&gt;
&lt;p&gt;Authority: spec.md R6 / #5187 (mission &lt;code dir=&quot;auto&quot;&gt;nightly-drift-reds-01M3M14S&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;scope-boundary-3&quot;&gt;Scope boundary&lt;/h3&gt;
&lt;p&gt;Only &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; is exempt. All other live &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; pages remain fully
scanned. This narrowness is pinned by &lt;code dir=&quot;auto&quot;&gt;test_docs_adr_exemption_is_narrow&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_terminology_guards.py&lt;/code&gt;, which asserts both that
&lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; is excluded and that live &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; pages outside every exempt
root are still being scanned.&lt;/p&gt;
&lt;p&gt;Because a “point-in-time snapshot” exemption is only safe as long as those
snapshots are never &lt;em&gt;published&lt;/em&gt; as live docs, every guard file listed under
“What is excluded” also carries a
&lt;code dir=&quot;auto&quot;&gt;test_docs_reports_exemption_is_not_published_as_live_docs&lt;/code&gt; guard. Each one
calls the shared &lt;code dir=&quot;auto&quot;&gt;assert_reports_unpublished&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/_support/reports_unpublished_guard.py&lt;/code&gt;, which fails when the docsite
contract (&lt;code dir=&quot;auto&quot;&gt;scripts/docs/_dockitty_contract.py&lt;/code&gt;) stops excluding &lt;code dir=&quot;auto&quot;&gt;reports/&lt;/code&gt; or
would publish any &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; page. If that guard ever fails, &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; has started being
published as live documentation and this exemption must be reconsidered, not
silently kept.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;exempt-surface-6-docsarchive--retired-pages-relocated-out-of-the-live-tree&quot;&gt;Exempt Surface 6: &lt;code dir=&quot;auto&quot;&gt;docs/archive/&lt;/code&gt; — Retired Pages Relocated Out of the Live Tree&lt;/h2&gt;
&lt;h3 id=&quot;what-is-excluded-5&quot;&gt;What is excluded&lt;/h3&gt;
&lt;p&gt;All files under &lt;code dir=&quot;auto&quot;&gt;docs/archive/&lt;/code&gt; are excluded from the live-doc scan in
&lt;code dir=&quot;auto&quot;&gt;_live_doc_scan_targets()&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;tests/contract/test_terminology_guards.py&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;FORBIDDEN_SCAN_ROOTS&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;why-it-is-exempt-5&quot;&gt;Why it is exempt&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;docs/archive/&lt;/code&gt; holds retired pages that #5428 (“archive retired pages and
neutralize 3.x-anchored names”) relocated out of the live tree. They are
immutable historical snapshots that legitimately retain era-correct wording
(the removed &lt;code dir=&quot;auto&quot;&gt;--feature&lt;/code&gt; alias, the pre-3.0 main-centric workflow, “Merge to
main”), exactly like &lt;code dir=&quot;auto&quot;&gt;docs/adr/&lt;/code&gt;. The Terminology Canon permits legacy wording
in explicitly archived artifacts, and rewording these pages would falsify the
record they exist to preserve. #5428 moved the pages but did not exempt the new
root, so the scan began flagging them (for example
&lt;code dir=&quot;auto&quot;&gt;docs/archive/plans/initiatives/test_improvement/IMPLEMENTATION_COMPLETE.md&lt;/code&gt;);
the exemption restores the archival carve-out (#5488).&lt;/p&gt;
&lt;h3 id=&quot;scope-boundary-4&quot;&gt;Scope boundary&lt;/h3&gt;
&lt;p&gt;Only &lt;code dir=&quot;auto&quot;&gt;docs/archive/&lt;/code&gt; is exempt. A retired page is exempt only because it lives
under this root: moving a page out of &lt;code dir=&quot;auto&quot;&gt;docs/archive/&lt;/code&gt; back into the live tree
puts it back in scope. All other live &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; pages remain fully scanned.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;shared-exempt-root-list-and-the-operator-surface-gates&quot;&gt;Shared Exempt-Root List and the Operator-Surface Gates&lt;/h2&gt;
&lt;p&gt;The exempt roots above are one list, &lt;code dir=&quot;auto&quot;&gt;FORBIDDEN_SCAN_ROOTS&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/_support/terminology_scope.py&lt;/code&gt;. The live-doc guard
(&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_terminology_guards.py&lt;/code&gt;) and the two operator-surface
gates added for #4836 read it, so a root exempted for one scan is exempted
for all:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_config_key_spelled_as_module_path.py&lt;/code&gt; — no
charter config key written as a &lt;code dir=&quot;auto&quot;&gt;charter.offering.*&lt;/code&gt; module path.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_deprecated_doctrine_command_in_guidance.py&lt;/code&gt; —
the removed-command gate: the &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; command group was removed in
#3732, so no living surface invokes it (the CLI name followed by
&lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt;) or names a backticked &lt;code dir=&quot;auto&quot;&gt;doctrine &amp;#x3C;former command&gt;&lt;/code&gt;. It scans the shipped skills, both
packs, the living docs, the CI workflows, &lt;code dir=&quot;auto&quot;&gt;Makefile&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;AGENTS.md&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;CLAUDE.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; and the full text of every Python file under &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;scripts/&lt;/code&gt; (docstrings and comments included). It has no allowlist.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Those two gates add the following exemptions on top of the shared list, each
for the reason given:&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Exemption&lt;/th&gt;&lt;th&gt;Gate&lt;/th&gt;&lt;th&gt;Reason&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/changelog/&lt;/code&gt; (both gates)&lt;/td&gt;&lt;td&gt;both&lt;/td&gt;&lt;td&gt;A changelog entry’s &lt;strong&gt;Before&lt;/strong&gt; quotes the old key or command. The live-doc guard’s Unreleased-only scan does not fit here, because the Unreleased section is exactly where those Before quotes live.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;removed-command gate&lt;/td&gt;&lt;td&gt;Plans and design reviews record how past work was planned and delivered (for example a work-package row recording that it added a subcommand to the &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; group). Rewriting a delivered work package’s command would falsify the record.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/development/docs-retrieval-index.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;removed-command gate&lt;/td&gt;&lt;td&gt;Generated output: it indexes every docs page, including the exempt historical roots. &lt;code dir=&quot;auto&quot;&gt;docs/api/cli-commands.md&lt;/code&gt; is scanned: it regenerates from the CLI’s help text, which no longer has the group.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Glob &lt;code dir=&quot;auto&quot;&gt;m_*charter_pack_cutover*.py&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/&lt;/code&gt; (today &lt;code dir=&quot;auto&quot;&gt;m_4_0_0rc6_charter_pack_cutover.py&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;removed-command gate&lt;/td&gt;&lt;td&gt;The cutover migration must spell the retired literals it rewrites.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;invariant-exemptions-must-stay-narrow&quot;&gt;Invariant: Exemptions Must Stay Narrow&lt;/h2&gt;
&lt;p&gt;Each exemption above is explicitly bounded. The guards include non-vacuity and
narrowness checks:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_docs_adr_exemption_is_narrow&lt;/code&gt; (in both guard files) confirms that live
&lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; pages outside the exempt roots are still being scanned; in
&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_terminology_guards.py&lt;/code&gt; it additionally confirms
&lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; is excluded.&lt;/li&gt;
&lt;li&gt;The CHANGELOG handling must remain via &lt;code dir=&quot;auto&quot;&gt;_extract_changelog_unreleased()&lt;/code&gt; rather
than a raw glob that would skip the file entirely.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_grep_guards_do_not_scan_historical_artifacts&lt;/code&gt; confirms that no glob
pattern in the guards directly targets any &lt;code dir=&quot;auto&quot;&gt;FORBIDDEN_SCAN_ROOTS&lt;/code&gt; root.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_docs_reports_exemption_is_not_published_as_live_docs&lt;/code&gt; (in both the
live-doc guard and the decision-command-shape guard) confirms
the docsite never publishes &lt;code dir=&quot;auto&quot;&gt;docs/reports/&lt;/code&gt; as live docs, so the
point-in-time-snapshot rationale for that exemption stays true.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;If a future change widens an exemption beyond its stated boundary — for example,
by exempting all of &lt;code dir=&quot;auto&quot;&gt;docs/plans/&lt;/code&gt; instead of only the three archival
subdirectories, or by treating all of &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; as historical — that is a
regression, not maintenance.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;updating-this-policy&quot;&gt;Updating This Policy&lt;/h2&gt;
&lt;p&gt;If a new surface requires an exemption:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Update &lt;code dir=&quot;auto&quot;&gt;FORBIDDEN_SCAN_ROOTS&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/_support/terminology_scope.py&lt;/code&gt; (shared by every terminology scan).&lt;/li&gt;
&lt;li&gt;Update &lt;code dir=&quot;auto&quot;&gt;_EXCLUDED_PATH_FRAGMENTS&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_legacy_terminology.py&lt;/code&gt; if the legacy-term scan
is also affected.&lt;/li&gt;
&lt;li&gt;Update this document to record the rationale and scope boundary for the new
exemption.&lt;/li&gt;
&lt;li&gt;Add or update a narrowness test that pins both the exempt surface and the
non-exempt remainder, so a future glob change cannot silently widen the
carve-out.&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
