<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-14-1-bulk-edit-occurrence-classification-guardrail/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-14-1-bulk-edit-occurrence-classification-guardrail/</id>
  <title>ADR 1 (2026-04-14): Bulk-Edit Occurrence Classification Guardrail</title>
  <updated>2026-04-14T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-14-1-bulk-edit-occurrence-classification-guardrail/"/>
  <summary>Bulk-edit missions must classify every occurrence into eight categories; review blocks when a changed file lands in a do-not-change category with no exception.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;When a codebase-wide edit changes a term — a rename, a terminology migration, a
package-path move, a feature-label swap — the &lt;strong&gt;same string&lt;/strong&gt; appears in
semantically different contexts. A token like &lt;code dir=&quot;auto&quot;&gt;constitution&lt;/code&gt; might appear as:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A Python class name (&lt;code dir=&quot;auto&quot;&gt;CompiledConstitution&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;An import path (&lt;code dir=&quot;auto&quot;&gt;from constitution.sync import sync&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;A filesystem path literal (&lt;code dir=&quot;auto&quot;&gt;&quot;.kittify/constitution/constitution.md&quot;&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;A serialized dict/YAML key (&lt;code dir=&quot;auto&quot;&gt;&quot;constitution_hash&quot;&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;A CLI command name (&lt;code dir=&quot;auto&quot;&gt;spec-kitty constitution sync&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;A log message or docstring&lt;/li&gt;
&lt;li&gt;A telemetry label referenced by dashboards&lt;/li&gt;
&lt;li&gt;A test fixture or snapshot&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Each category has &lt;strong&gt;different change rules&lt;/strong&gt;. A Python class name can be safely
renamed. A serialized dict key writes to existing data files that downstream
systems read — renaming the key breaks deserialization. A CLI command name is a
public API with users running scripts — renaming breaks those scripts. A
telemetry label is referenced by dashboards, alerts, and queries outside the
repo — renaming silently bifurcates metrics.&lt;/p&gt;
&lt;p&gt;Mechanical find-and-replace (&lt;code dir=&quot;auto&quot;&gt;sed&lt;/code&gt;, LLM mass-edit, IDE rename refactor) treats
all of these as a single operation. The edits produce no warnings. Tests and
build systems often don’t catch the breakage because the code still compiles
and unit tests pass — the harm is in the data layer, the API contract, or the
observability surface. The failure only surfaces in production, long after the
diff is merged.&lt;/p&gt;
&lt;p&gt;Spec Kitty missions have no workflow mechanism to force a deliberate
per-category classification before bulk edits begin. This is the failure shape
issue #393 was created to close.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Bulk renames and terminology migrations are common and will recur; the
system must prevent the silent-breakage class without requiring a new mission
type or a parallel review mechanism for every mission.&lt;/li&gt;
&lt;li&gt;The cost of a false negative (an unchecked bulk edit corrupting serialized
data or breaking a CLI) is orders of magnitude higher than the cost of a
false positive (an author drafts an occurrence map the user approves in one
pass).&lt;/li&gt;
&lt;li&gt;The guardrail must work identically across all 12 supported AI agents
(Claude Code, Codex, Gemini, Copilot, OpenCode, Qwen, Cursor, Windsurf,
Kilocode, Augment, Roo, Q) without agent-specific behavior.&lt;/li&gt;
&lt;li&gt;Existing doctrine extensibility (directives + tactics, &lt;code dir=&quot;auto&quot;&gt;mission_v1&lt;/code&gt; guard
registry, expected-artifacts manifest) should be preferred over new
infrastructure.&lt;/li&gt;
&lt;li&gt;The user of spec-kitty never says “bulk edit”; they say “rename Coffee to
Tea.” Therefore the workflow must be &lt;strong&gt;agent-driven&lt;/strong&gt;, not user-declarative.&lt;/li&gt;
&lt;li&gt;The Spec Kitty CLI is the only layer where edits can be gated &lt;strong&gt;before they
begin&lt;/strong&gt; (pre-commit, CI, and PR review all run after the mechanical rename
has already happened).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A:&lt;/strong&gt; New workflow step type (&lt;code dir=&quot;auto&quot;&gt;classify_occurrences&lt;/code&gt;) injected into
mission configs, surfaced on the dashboard, tracked as a first-class status
lane, with its own approval cycle.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B:&lt;/strong&gt; Guard condition on the existing &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt;
actions. A classification artifact (&lt;code dir=&quot;auto&quot;&gt;occurrence_map.yaml&lt;/code&gt;) is a mission-level
planning deliverable; the guard blocks action dispatch when the mission is
marked &lt;code dir=&quot;auto&quot;&gt;change_mode: bulk_edit&lt;/code&gt; and the artifact is absent or inadmissible.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C:&lt;/strong&gt; Post-hoc validation — accept any edit, detect violations via a
pre-merge or CI-level scan (git hook or GitHub Action) that grep-classifies
the diff.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option D:&lt;/strong&gt; AST-level or tree-sitter-level occurrence classification that
inspects every changed line and assigns a semantic category, then enforces
per-category rules at the line level.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Within the gate for option B, three sub-options on review-time compliance were
considered:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;B.1:&lt;/strong&gt; Artifact-admissibility only. Review checks that the map exists and
is structurally valid; human/AI reviewer uses the map as a reference.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B.2:&lt;/strong&gt; Path-heuristic diff compliance. Review additionally inspects the
git diff, classifies each changed file by filesystem path and extension, and
rejects when a changed file lands in a &lt;code dir=&quot;auto&quot;&gt;do_not_change&lt;/code&gt; category or cannot be
mapped.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B.3:&lt;/strong&gt; Full semantic diff compliance. Review parses each changed file,
identifies individual occurrences of the target string, classifies each one,
and rejects at line granularity.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Adopt &lt;strong&gt;Option B&lt;/strong&gt;: guard condition on the &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt; actions, driven
by a mission-level &lt;code dir=&quot;auto&quot;&gt;change_mode: bulk_edit&lt;/code&gt; flag and an &lt;code dir=&quot;auto&quot;&gt;occurrence_map.yaml&lt;/code&gt;
artifact that classifies the 8 standard occurrence categories with per-category
actions (&lt;code dir=&quot;auto&quot;&gt;rename&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;manual_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;do_not_change&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;rename_if_user_visible&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;Within Option B, adopt &lt;strong&gt;B.2&lt;/strong&gt;: path-heuristic diff compliance at review time.
The gate inspects &lt;code dir=&quot;auto&quot;&gt;git diff --name-only&lt;/code&gt;, classifies each changed file by path
pattern, and blocks the review when any changed file is classified into a
&lt;code dir=&quot;auto&quot;&gt;do_not_change&lt;/code&gt; category or cannot be mapped to any category and no matching
exception is declared. Exceptions in the map can override category rules on a
per-path basis with a documented &lt;code dir=&quot;auto&quot;&gt;reason:&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Activate the workflow &lt;strong&gt;via an agent skill&lt;/strong&gt;, not via user declaration. The
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-bulk-edit-classification&lt;/code&gt; doctrine skill teaches agents to recognize
bulk-edit intent in user requests (“rename X to Y”, “the Blue feature is now
Red”) during specify/plan, set &lt;code dir=&quot;auto&quot;&gt;change_mode&lt;/code&gt; on the user’s behalf, draft the
occurrence map, and interview the user about per-category actions in plain
language. Trigger references in the specify and plan command templates point
agents to the skill at the right phase boundaries.&lt;/p&gt;
&lt;p&gt;Codify the governance rule as a doctrine directive (&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_035&lt;/code&gt;) referencing a
new tactic (&lt;code dir=&quot;auto&quot;&gt;occurrence-classification-workflow&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;Defer Option D (full semantic classification) to a future hardening mission.&lt;/p&gt;
&lt;h2 id=&quot;rationale&quot;&gt;Rationale&lt;/h2&gt;
&lt;h3 id=&quot;why-b-over-a-c-and-d&quot;&gt;Why B over A, C, and D&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Why not A (first-class workflow step):&lt;/strong&gt; The classification decision is a
mission-level planning deliverable, not a work-package output. Treating it as a
workflow step would require new step types, new dashboard semantics, new
status-lane accounting, and a new approval cycle — infrastructure weight out of
proportion to the value. A guard condition on &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; enforces the rule at
the only point that matters (before edits begin) without requiring any of that
infrastructure. A follow-on mission can promote B to a first-class step if
dashboard visibility becomes important; demoting A would be significantly
harder.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Why not C (post-hoc validation):&lt;/strong&gt; By the time CI runs, the mechanical rename
has already happened. Violations show up as PR blockers that force a full
re-implementation rather than a deliberate up-front classification. Post-hoc
validation is valuable as a &lt;strong&gt;backstop&lt;/strong&gt; but cannot replace the pre-edit
classification step that gives #393 its value. The guard fires at the one
moment where the author is positioned to decide; CI fires at the moment where
the author must fix or revert.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Why not D (full semantic classification):&lt;/strong&gt; Out of scope per constraint
C-001. Full semantic classification requires per-language AST or tree-sitter
infrastructure for every language in the repo, plus heuristics for
distinguishing identifiers from string literals inside a single file. The
maintenance cost of that across 12 agents and the full matrix of supported
languages is prohibitive for v1. Path-heuristic classification at the file
granularity captures the most common silent-breakage shapes (serialized-key
YAML files, CLI command modules, test fixtures, telemetry config) without
touching source parsing.&lt;/p&gt;
&lt;h3 id=&quot;why-b2-over-b1&quot;&gt;Why B.2 over B.1&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;B.1 shipped first and was immediately critiqued&lt;/strong&gt; in post-merge review (P1
finding, this ADR supersedes it). The critique was correct: “review validates
the artifact exists” does not satisfy FR-007/FR-008’s actual requirement that
review &lt;em&gt;reject diffs that violate the classification&lt;/em&gt;. The map is a contract;
B.1 only verified the contract was written, not that execution respected it.&lt;/p&gt;
&lt;p&gt;B.2 runs path-heuristic classification at the file level. This is imperfect —
a &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; file mixes code symbols, import paths, string literals, and log
messages, and path heuristics cannot distinguish them — but it is sufficient
to catch the highest-value failure classes: whole-file modifications inside a
protected surface. The exception mechanism (glob patterns with action
overrides and documented reasons) bridges the cases where the heuristic is too
coarse or too fine.&lt;/p&gt;
&lt;h3 id=&quot;why-b3-is-out-of-scope&quot;&gt;Why B.3 is out of scope&lt;/h3&gt;
&lt;p&gt;Full semantic diff compliance requires language-aware occurrence detection
(C-001 excludes this) and a per-occurrence classification model. Building that
for v1 would delay delivery by an order of magnitude. B.2’s path-level
classification addresses the failure classes that motivated #393 (serialized
keys, CLI surfaces, telemetry labels, test fixtures) and leaves line-level
refinement to a future mission.&lt;/p&gt;
&lt;h3 id=&quot;why-agent-driven-not-user-declarative&quot;&gt;Why agent-driven, not user-declarative&lt;/h3&gt;
&lt;p&gt;A declarative model requires every spec author to know the &lt;code dir=&quot;auto&quot;&gt;change_mode&lt;/code&gt; field
exists and remember to set it. This requirement is not satisfiable by the
product’s users, who describe changes in product language (“rename Coffee to
Tea”), not operational language (“this is a bulk-edit mission”). Either the
system becomes something only expert users can drive — which fails
constraint C-004’s breadth requirement — or the agent closes the knowledge
gap on the user’s behalf.&lt;/p&gt;
&lt;p&gt;The doctrine skill is the load-bearing piece of this decision. Without it, the
guardrail exists but is invisible to the people and agents who should be
applying it. The command-template triggers ensure the skill is loaded at the
right phase (specify, plan) without expanding prompt surface at other phases.&lt;/p&gt;
&lt;h3 id=&quot;why-the-runtime-gate-has-no-bypass-flag&quot;&gt;Why the runtime gate has no bypass flag&lt;/h3&gt;
&lt;p&gt;The artifact-admissibility gate and the diff-compliance gate both exit with a
hard error and no bypass flag. Intentional. The mechanism that blocks must be
stronger than a stray keyword or a tired reviewer. If the gate is wrong on a
specific case, the remediation is &lt;strong&gt;editing the occurrence map&lt;/strong&gt; (an
auditable, reviewable change with a recorded &lt;code dir=&quot;auto&quot;&gt;reason:&lt;/code&gt;), not a silent
command-line flag that leaves no trace. This places the friction where it
belongs: on deliberate rule modification, not on runtime execution.&lt;/p&gt;
&lt;p&gt;The inference warning (&lt;code dir=&quot;auto&quot;&gt;--acknowledge-not-bulk-edit&lt;/code&gt;) is the exception to this
rule and is deliberately advisory, because it fires when &lt;code dir=&quot;auto&quot;&gt;change_mode&lt;/code&gt; is
&lt;strong&gt;not&lt;/strong&gt; set — i.e., the mission may not be a bulk edit at all, and a blocking
false positive in that path is worse than a bypassable false positive.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Missions that describe bulk edits cannot begin implementation without an
explicit, per-category classification decision.&lt;/li&gt;
&lt;li&gt;High-risk surfaces (serialized keys, CLI commands, telemetry labels) that
would silently break under mechanical rename are protected by default.&lt;/li&gt;
&lt;li&gt;The 8 standard categories force the author to consider every risk surface,
even ones they would not have thought to check (&lt;code dir=&quot;auto&quot;&gt;logs_telemetry&lt;/code&gt; is a
common blind spot).&lt;/li&gt;
&lt;li&gt;Doctrine extensibility is preserved — the feature uses existing mechanisms
(directive + tactic, mission_v1 guard, expected-artifacts manifest) without
adding new infrastructure.&lt;/li&gt;
&lt;li&gt;The skill-driven activation model lets the guardrail protect users who
have no knowledge of its existence. The feature scales to new contributors
without training.&lt;/li&gt;
&lt;li&gt;The diff-compliance gate at review time is independent of the implement-time
gate and provides a second check: implementation happened, did it stay
within the classified surfaces?&lt;/li&gt;
&lt;li&gt;The audit trail is strong. Every exception in the occurrence map carries a
&lt;code dir=&quot;auto&quot;&gt;reason:&lt;/code&gt; string. Any loosening of a &lt;code dir=&quot;auto&quot;&gt;do_not_change&lt;/code&gt; rule is visible in
git history.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Path-heuristic classification is imperfect. A &lt;code dir=&quot;auto&quot;&gt;.json&lt;/code&gt; file carrying
translation keys is treated identically to a &lt;code dir=&quot;auto&quot;&gt;.json&lt;/code&gt; file carrying API
schema. Authors must use exceptions to distinguish — real friction when the
repo’s file conventions are not aligned with the heuristic’s assumptions.&lt;/li&gt;
&lt;li&gt;Unclassified file types (&lt;code dir=&quot;auto&quot;&gt;.graphql&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.proto&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.prisma&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.sol&lt;/code&gt;,
domain-specific formats) block review until the author adds an explicit
exception. This is intentional (FR-008) but adds setup cost for repos with
unusual file types.&lt;/li&gt;
&lt;li&gt;The 8-category requirement forces authors to classify categories that may
not apply to their specific rename (e.g., a UI-only change still has to
declare &lt;code dir=&quot;auto&quot;&gt;logs_telemetry: do_not_change&lt;/code&gt;). This is a deliberate tradeoff —
silent whitelisting of risk surfaces was the bug we were fixing.&lt;/li&gt;
&lt;li&gt;The guardrail only fires when the agent correctly detects bulk-edit intent
during specify/plan. An agent that mis-classifies intent produces a
false-negative silent rename exactly as before. The inference warning is
the backstop but is advisory only.&lt;/li&gt;
&lt;li&gt;No cryptographic freezing of the occurrence map. An agent that edits the
map mid-WP to exception-away a violation will pass the gate, and only
careful reviewer attention to map-history diffs will catch it. Future
hardening can add map-timestamp comparison.&lt;/li&gt;
&lt;li&gt;Exceptions are not required to carry a &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt;. A well-meaning agent can
add &lt;code dir=&quot;auto&quot;&gt;{ path: &quot;foo&quot;, action: rename }&lt;/code&gt; with no justification. Future
hardening can require non-empty reasons.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Review cycle time on bulk-edit missions is slightly longer because of the
additional diff-classification step. Negligible (&amp;#x3C; 1s on realistic diffs).&lt;/li&gt;
&lt;li&gt;Missions without &lt;code dir=&quot;auto&quot;&gt;change_mode: bulk_edit&lt;/code&gt; experience zero additional gates
or delays. NFR-005.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;implementation-notes&quot;&gt;Implementation Notes&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Directive: &lt;code dir=&quot;auto&quot;&gt;src/doctrine/directives/shipped/035-bulk-edit-occurrence-classification.directive.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Tactic: &lt;code dir=&quot;auto&quot;&gt;src/doctrine/tactics/built-in/occurrence-classification-workflow.tactic.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Skill: &lt;code dir=&quot;auto&quot;&gt;src/doctrine/skills/spec-kitty-bulk-edit-classification/SKILL.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Mission metadata field: &lt;code dir=&quot;auto&quot;&gt;change_mode&lt;/code&gt; (optional, valid values: &lt;code dir=&quot;auto&quot;&gt;&quot;bulk_edit&quot;&lt;/code&gt;)
in &lt;code dir=&quot;auto&quot;&gt;MissionMetaOptional&lt;/code&gt; TypedDict.&lt;/li&gt;
&lt;li&gt;Artifact: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;mission&gt;/occurrence_map.yaml&lt;/code&gt; with required
&lt;code dir=&quot;auto&quot;&gt;target&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;categories&lt;/code&gt; (all 8 standard names), and optional &lt;code dir=&quot;auto&quot;&gt;exceptions&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; sections.&lt;/li&gt;
&lt;li&gt;Gate function: &lt;code dir=&quot;auto&quot;&gt;specify_cli.bulk_edit.gate.ensure_occurrence_classification_ready&lt;/code&gt;
is invoked from &lt;code dir=&quot;auto&quot;&gt;cli/commands/implement.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;cli/commands/agent/workflow.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Diff checker: &lt;code dir=&quot;auto&quot;&gt;specify_cli.bulk_edit.diff_check.check_diff_compliance&lt;/code&gt;
is invoked from the review path after artifact admissibility passes.&lt;/li&gt;
&lt;li&gt;Inference warning: &lt;code dir=&quot;auto&quot;&gt;specify_cli.bulk_edit.inference.scan_spec_file&lt;/code&gt;
fires in the implement command when &lt;code dir=&quot;auto&quot;&gt;change_mode&lt;/code&gt; is not set and spec
content scores &gt;= 4 against weighted keyword patterns.&lt;/li&gt;
&lt;li&gt;Command template triggers: &lt;code dir=&quot;auto&quot;&gt;specify.md&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; under
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/software-dev/command-templates/&lt;/code&gt; point agents to
the skill at the relevant phase boundaries.&lt;/li&gt;
&lt;li&gt;Guard registration: &lt;code dir=&quot;auto&quot;&gt;occurrence_map_complete&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;specify_cli.mission_v1.guards.GUARD_REGISTRY&lt;/code&gt; provides a declarative hook
for future mission configs to reference the check from a state-machine
transition. The primary enforcement path is the direct function call from
the CLI commands, not the guard primitive.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;related-decisions-and-references&quot;&gt;Related Decisions and References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Issue: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/393&quot;&gt;Priivacy-ai/spec-kitty#393&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Parent: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/391&quot;&gt;#391 Tech Debt Remediation&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Mission dir: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/bulk-edit-occurrence-classification-guardrail-01KP423X/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Mission review report: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/bulk-edit-occurrence-classification-guardrail-01KP423X/mission-review.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Related directive: &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_035&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Related tactic: &lt;code dir=&quot;auto&quot;&gt;occurrence-classification-workflow&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Related skill: &lt;code dir=&quot;auto&quot;&gt;spec-kitty-bulk-edit-classification&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Related ADR: none (first guardrail of this shape in spec-kitty)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;follow-on-work&quot;&gt;Follow-On Work&lt;/h2&gt;
&lt;p&gt;Documented but deferred:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Map-history attestation: compare occurrence map at first-WP-implement time
vs. at review time, flag any loosening of &lt;code dir=&quot;auto&quot;&gt;do_not_change&lt;/code&gt; rules.&lt;/li&gt;
&lt;li&gt;Per-exception &lt;code dir=&quot;auto&quot;&gt;reason:&lt;/code&gt; enforcement in the schema.&lt;/li&gt;
&lt;li&gt;Full semantic diff classification (Option D) for repos where file-level
path heuristics produce too many false positives or negatives.&lt;/li&gt;
&lt;li&gt;Promote the guard to a first-class workflow step (Option A) if dashboard
visibility of classification status becomes a user need.&lt;/li&gt;
&lt;li&gt;Extend path heuristics to domain-specific file types (&lt;code dir=&quot;auto&quot;&gt;.graphql&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.proto&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;.prisma&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.sol&lt;/code&gt;) once usage patterns emerge.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
