<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/1.x/2026-01-25-9-deterministic-csv-schema-enforcement/">
  <id>https://docs.spec-kitty.ai/adr/1.x/2026-01-25-9-deterministic-csv-schema-enforcement/</id>
  <title>ADR 8: Deterministic CSV Schema Enforcement for Research Missions</title>
  <updated>2026-01-25T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/1.x/2026-01-25-9-deterministic-csv-schema-enforcement/"/>
  <summary>Pins the evidence-log and source-register column schemas and surfaces mismatches at upgrade time, rather than silently rewriting a researcher&apos;s collected data.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Research missions use two CSV files for planning artifacts:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;evidence-log.csv&lt;/code&gt;: Citations with findings, confidence levels, timestamps&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;source-register.csv&lt;/code&gt;: Master list of sources with metadata&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Each CSV has a &lt;strong&gt;canonical schema&lt;/strong&gt; defined in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/validators/research.py&lt;/code&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;evidence-log.csv&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;timestamp,source_type,citation,key_finding,confidence,notes&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;source-register.csv&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;source_id,citation,url,accessed_date,relevance,status&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;the-problem&quot;&gt;The Problem&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Agents modify CSV schemas during implementation, causing merge conflicts and validation failures:&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Real-World Example:&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;# Main branch (created during /spec-kitty.research):&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;evidence_id,component,finding,citation,confidence,timestamp,notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;# WP01 worktree (agent created different schema):&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;component_name,category,citation,confidence,finding_type,notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;# Result: Merge conflict, both schemas wrong, validation blocks review&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Root Cause:&lt;/strong&gt; Schemas are defined and validated, but &lt;strong&gt;not visible to agents&lt;/strong&gt; until review (too late).&lt;/p&gt;
&lt;h3 id=&quot;why-this-happens&quot;&gt;Why This Happens&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Schema Visibility Gap&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Canonical schema exists in Python validators&lt;/li&gt;
&lt;li&gt;Template CSV has correct schema with comments&lt;/li&gt;
&lt;li&gt;But implement.md (agent’s instructions) doesn’t document schemas&lt;/li&gt;
&lt;li&gt;Agents see task description, not schema requirements&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Late Validation&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Validation only runs during &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.review&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;By then, agent has committed wrong schema&lt;/li&gt;
&lt;li&gt;Fixing requires rebasing, manual CSV migration&lt;/li&gt;
&lt;li&gt;Blocks review workflow&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;No Protection&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agents can overwrite entire CSV file&lt;/li&gt;
&lt;li&gt;Template with correct schema gets replaced&lt;/li&gt;
&lt;li&gt;No early warnings during implementation&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Nondeterminism&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Different agents invent different schemas&lt;/li&gt;
&lt;li&gt;Parallel WPs create conflicting schemas&lt;/li&gt;
&lt;li&gt;No “intelligent” merge strategy for CSV headers&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Agent behavior&lt;/strong&gt;: LLM agents follow visible instructions; if schema not documented, they guess&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Merge conflicts&lt;/strong&gt;: Wrong schemas create unmergeable conflicts at review time&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User data integrity&lt;/strong&gt;: Auto-migration risks data loss (ad hoc schemas in wild)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Developer experience&lt;/strong&gt;: Late-stage validation blocks workflow, frustrates users&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Maintainability&lt;/strong&gt;: Schema should be defined once, propagated everywhere&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Make CSVs read-only (append-only)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pre-commit hooks to validate schemas&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Document schemas in agent-visible locations&lt;/strong&gt; ⭐ (chosen)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Auto-migrate wrong schemas during upgrade&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Document schemas in agent-visible locations + detection migration”, because:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Prevention over cure&lt;/strong&gt;: Agents see schema before editing, preventing wrong schemas&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No data loss risk&lt;/strong&gt;: Users manually migrate with LLM help (no auto-fix)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Early detection&lt;/strong&gt;: Upgrade migration informs users of mismatches&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Empowers users&lt;/strong&gt;: Clear schema documentation + migration tips&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;implementation&quot;&gt;Implementation&lt;/h3&gt;
&lt;h4 id=&quot;1-document-schemas-in-agent-templates&quot;&gt;1. Document Schemas in Agent Templates&lt;/h4&gt;
&lt;p&gt;Add “Research CSV Schemas” section to &lt;code dir=&quot;auto&quot;&gt;implement.md&lt;/code&gt; for all 12 agents:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82B1FF;--1:#3B61B0&quot;&gt;## Research CSV Schemas (CRITICAL - DO NOT MODIFY HEADERS)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82B1FF;--1:#3B61B0&quot;&gt;### evidence-log.csv Schema&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;Required columns (exact order):&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;timestamp,source_type,citation,key_finding,confidence,notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;| Column | Type | Valid Values |&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;|--------|------|--------------|&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;| timestamp | ISO datetime | YYYY-MM-DDTHH:MM:SS |&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;| source_type | Enum | journal | conference | book | web | preprint |&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;| citation | Text | BibTeX, APA, or Simple format |&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;| key_finding | Text | 1-2 sentences |&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;| confidence | Enum | high | medium | low |&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;| notes | Text | Free text |&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;To add evidence (append only, never edit headers):&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;echo &apos;2025-01-25T14:00:00,journal,&quot;Citation&quot;,Finding,high,Notes&apos; &gt;&gt; evidence-log.csv&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Why this works:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agents read implement.md before starting work&lt;/li&gt;
&lt;li&gt;Schema is visible, concrete, with examples&lt;/li&gt;
&lt;li&gt;Warning about validation blocking review&lt;/li&gt;
&lt;li&gt;Append-only pattern prevents overwrites&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;2-schema-validator-utility&quot;&gt;2. Schema Validator Utility&lt;/h4&gt;
&lt;p&gt;Create &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/validators/csv_schema.py&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;@dataclass&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;class&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FFCB8B;--1:#111111&quot;&gt;CSVSchemaValidation&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;file_path: Path&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;expected_columns: list[&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;str&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;actual_columns: list[&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;str&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;] &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;None&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;schema_valid: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;bool&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;error_message: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;str&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;None&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;validate_csv_schema&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;csv_path&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;expected_columns&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Exact match: names AND order&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Reusable for:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Upgrade migrations (detection)&lt;/li&gt;
&lt;li&gt;Validators (existing citation validation)&lt;/li&gt;
&lt;li&gt;Future CSV additions&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;3-detection-migration-informational&quot;&gt;3. Detection Migration (Informational)&lt;/h4&gt;
&lt;p&gt;Create &lt;code dir=&quot;auto&quot;&gt;m_0_13_0_research_csv_schema_check.py&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;apply&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;project_path&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; feature &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; research_features:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;        &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;validate evidence&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;log.csv schema&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;        &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;validate source&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;register.csv schema&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; mismatch:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;            &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;print&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;informational_report_with_tips&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# NO AUTO-FIX&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Output when wrong schema detected:&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;📋 Research CSV Schema Check (Informational)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;002-feature/research/evidence-log.csv:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Expected: timestamp,source_type,citation,key_finding,confidence,notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Actual:   evidence_id,component,finding,citation,confidence,timestamp,notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;💡 To fix this schema mismatch:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;     &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;1. Read canonical schema in .claude/commands/spec-kitty.implement.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;     &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;2. Create new CSV with correct headers&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;     &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;3. Map old data → new schema (LLM agents can help)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;     &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;4. Replace old file&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h4 id=&quot;4-template-propagation-migration&quot;&gt;4. Template Propagation Migration&lt;/h4&gt;
&lt;p&gt;Create &lt;code dir=&quot;auto&quot;&gt;m_0_13_0_update_research_implement_templates.py&lt;/code&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Copies updated &lt;code dir=&quot;auto&quot;&gt;implement.md&lt;/code&gt; from packaged missions&lt;/li&gt;
&lt;li&gt;Updates all 12 agent directories&lt;/li&gt;
&lt;li&gt;Only updates research templates (skips software-dev)&lt;/li&gt;
&lt;li&gt;Idempotent (safe to run multiple times)&lt;/li&gt;
&lt;li&gt;Respects agent configuration&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Prevention&lt;/strong&gt;: Agents see schema before editing (no more wrong schemas)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Visibility&lt;/strong&gt;: Schema documented where agents look (implement.md)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Safety&lt;/strong&gt;: No auto-migration (respects user data)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Actionable&lt;/strong&gt;: Detection migration provides clear migration path&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reusable&lt;/strong&gt;: Schema validator utility for future CSV files&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Maintainable&lt;/strong&gt;: Single source of truth in validator, propagated to templates&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Manual migration required&lt;/strong&gt;: Users must fix existing wrong schemas themselves&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Documentation overhead&lt;/strong&gt;: Schema appears in multiple locations (validator + 12 agent templates)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No runtime enforcement&lt;/strong&gt;: Agents can still overwrite if they ignore instructions&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Delayed fix&lt;/strong&gt;: Existing projects with wrong schemas not auto-fixed&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Migration is informational only (non-blocking)&lt;/li&gt;
&lt;li&gt;Users discover mismatches during upgrade, not during review&lt;/li&gt;
&lt;li&gt;LLM agents can help with migration (documented in tips)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Metrics to validate this decision:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Schema compliance rate&lt;/strong&gt;: % of new research features with correct schemas&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Merge conflict rate&lt;/strong&gt;: Reduced CSV schema conflicts during review&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User reports&lt;/strong&gt;: Fewer “validation blocked my review” issues&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Agent behavior&lt;/strong&gt;: Agents preserve schemas when templates updated&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Success criteria:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Zero schema mismatches in new research features after 0.13.0&lt;/li&gt;
&lt;li&gt;Existing users successfully migrate wrong schemas with LLM help&lt;/li&gt;
&lt;li&gt;No data loss reports from auto-migration (N/A - we don’t auto-migrate)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-make-csvs-read-only-append-only&quot;&gt;Option 1: Make CSVs Read-Only (Append-Only)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Description:&lt;/strong&gt; Use &lt;code dir=&quot;auto&quot;&gt;chmod 444&lt;/code&gt; to make CSV files read-only, forcing append-only writes.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Strongest enforcement - agents cannot overwrite headers&lt;/li&gt;
&lt;li&gt;Simple, deterministic, foolproof&lt;/li&gt;
&lt;li&gt;Works even if agents ignore instructions&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;File permissions fragile (git doesn’t preserve)&lt;/li&gt;
&lt;li&gt;Breaks legitimate use cases (bulk import)&lt;/li&gt;
&lt;li&gt;Harder to troubleshoot (permission errors confusing)&lt;/li&gt;
&lt;li&gt;Not portable (Windows file permissions different)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Too restrictive, fragile file permissions, poor UX for legitimate edits.&lt;/p&gt;
&lt;h3 id=&quot;option-2-pre-commit-hook-validation&quot;&gt;Option 2: Pre-Commit Hook Validation&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Description:&lt;/strong&gt; Git hook validates CSV schemas before every commit, blocks if wrong.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Automatic enforcement at commit time&lt;/li&gt;
&lt;li&gt;Early detection (before review)&lt;/li&gt;
&lt;li&gt;Works for all agents (universal)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires git hook setup (not all users have hooks)&lt;/li&gt;
&lt;li&gt;Agents can bypass with &lt;code dir=&quot;auto&quot;&gt;--no-verify&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Surprising failures (agent doesn’t know why commit blocked)&lt;/li&gt;
&lt;li&gt;Harder to debug (hook errors opaque)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Relies on hook setup, can be bypassed, poor error messages for agents.&lt;/p&gt;
&lt;h3 id=&quot;option-3-document-schemas-in-agent-visible-locations-&quot;&gt;Option 3: Document Schemas in Agent-Visible Locations ⭐&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Description:&lt;/strong&gt; Add schema documentation to implement.md templates that agents read.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preventative - agents see schema before editing&lt;/li&gt;
&lt;li&gt;Clear, visible, with examples&lt;/li&gt;
&lt;li&gt;Works with agent workflow (read instructions first)&lt;/li&gt;
&lt;li&gt;No runtime dependencies (hooks, permissions)&lt;/li&gt;
&lt;li&gt;Users in control (can still override if needed)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Relies on agents reading instructions&lt;/li&gt;
&lt;li&gt;Not enforced at runtime&lt;/li&gt;
&lt;li&gt;Schema duplicated across 12 agent templates&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Chosen:&lt;/strong&gt; Best balance of prevention, visibility, and user control. Works with agent behavior.&lt;/p&gt;
&lt;h3 id=&quot;option-4-auto-migrate-wrong-schemas-during-upgrade&quot;&gt;Option 4: Auto-Migrate Wrong Schemas During Upgrade&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Description:&lt;/strong&gt; Migration automatically fixes wrong schemas by mapping columns.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Zero user effort (automatic fix)&lt;/li&gt;
&lt;li&gt;Immediate resolution (no manual migration)&lt;/li&gt;
&lt;li&gt;Works for all projects (universal)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Risk of data loss&lt;/strong&gt;: Mapping arbitrary schemas error-prone&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unknown schemas&lt;/strong&gt;: Ad hoc schemas in wild (can’t predict all)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User trust&lt;/strong&gt;: Auto-modifying data without permission concerning&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Complexity&lt;/strong&gt;: Requires schema inference, column mapping logic&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Too risky - users know their data best, auto-migration could corrupt data.&lt;/p&gt;
&lt;h2 id=&quot;implementation-details&quot;&gt;Implementation Details&lt;/h2&gt;
&lt;h3 id=&quot;files-created&quot;&gt;Files Created&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/validators/csv_schema.py&lt;/code&gt; - Reusable schema validator&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_0_13_0_research_csv_schema_check.py&lt;/code&gt; - Detection migration&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_0_13_0_update_research_implement_templates.py&lt;/code&gt; - Template propagation&lt;/li&gt;
&lt;li&gt;Comprehensive test suite (53 tests, 100% passing)&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;files-modified&quot;&gt;Files Modified&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/validators/research.py&lt;/code&gt; - Export schema constants&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/research/command-templates/implement.md&lt;/code&gt; - Add schema documentation&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;schema-constants&quot;&gt;Schema Constants&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame has-title not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;src/specify_cli/validators/research.py&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;EVIDENCE_REQUIRED_COLUMNS&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;[&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;timestamp&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;source_type&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;citation&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;key_finding&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;confidence&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;notes&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;SOURCE_REGISTER_REQUIRED_COLUMNS&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;[&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;source_id&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;citation&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;url&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;accessed_date&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;relevance&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Now exported in &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; for use by migrations, validators, and future tools.&lt;/p&gt;
&lt;h2 id=&quot;testing-strategy&quot;&gt;Testing Strategy&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Unit Tests (13 tests):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/validators/test_csv_schema.py&lt;/code&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Correct schema validation&lt;/li&gt;
&lt;li&gt;Wrong column names/order detection&lt;/li&gt;
&lt;li&gt;Missing/extra columns detection&lt;/li&gt;
&lt;li&gt;File not found handling&lt;/li&gt;
&lt;li&gt;Whitespace handling&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Integration Tests - Detection (15 tests):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/test_research_csv_schema_migration.py&lt;/code&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No features handling&lt;/li&gt;
&lt;li&gt;Correct schema (no report)&lt;/li&gt;
&lt;li&gt;Wrong evidence/source schemas (informational report)&lt;/li&gt;
&lt;li&gt;Software-dev feature skipping&lt;/li&gt;
&lt;li&gt;Multiple features (mixed correct/wrong)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Integration Tests - Templates (25 tests):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/test_research_implement_template_migration.py&lt;/code&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;All 12 agents updated (parametrized)&lt;/li&gt;
&lt;li&gt;Agent config respected&lt;/li&gt;
&lt;li&gt;Software-dev templates skipped&lt;/li&gt;
&lt;li&gt;Idempotent migration&lt;/li&gt;
&lt;li&gt;Dry-run mode&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Total:&lt;/strong&gt; 53 tests, 100% passing&lt;/p&gt;
&lt;h2 id=&quot;related-decisions&quot;&gt;Related Decisions&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;ADR 6&lt;/strong&gt;: Config-Driven Agent Management (similar config-aware migration pattern)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ADR 7&lt;/strong&gt;: Research Deliverables Separation (research mission architecture)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Issue: &lt;em&gt;“Agents modify CSV schemas during implementation, causing merge conflicts”&lt;/em&gt;&lt;/li&gt;
&lt;li&gt;Plan: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/0XX-deterministic-csv-schema-enforcement/plan.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Implementation PR: &lt;em&gt;“feat: Document research CSV schemas in agent templates + detection migration”&lt;/em&gt;&lt;/li&gt;
&lt;li&gt;Canonical schemas: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/validators/research.py:29-45&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Template source: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/research/command-templates/implement.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;migration-path-for-users&quot;&gt;Migration Path for Users&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;For users with existing wrong schemas:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; (triggers detection migration)&lt;/li&gt;
&lt;li&gt;See informational report with schema diffs&lt;/li&gt;
&lt;li&gt;Read canonical schema in &lt;code dir=&quot;auto&quot;&gt;.claude/commands/spec-kitty.implement.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Use LLM agent to help migrate data:
&lt;ul&gt;
&lt;li&gt;Create new CSV with correct headers&lt;/li&gt;
&lt;li&gt;Map old columns → new columns&lt;/li&gt;
&lt;li&gt;Validate data integrity&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Replace old file&lt;/li&gt;
&lt;li&gt;Commit to main branch&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;For new research features (0.13.0+):&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Templates already have correct schemas&lt;/li&gt;
&lt;li&gt;Agents see schema documentation in implement.md&lt;/li&gt;
&lt;li&gt;Follow append-only pattern (no overwrites)&lt;/li&gt;
&lt;li&gt;Validation passes at review&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;future-enhancements&quot;&gt;Future Enhancements&lt;/h2&gt;
&lt;p&gt;Potential improvements (not in 0.13.0):&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Pre-commit hook&lt;/strong&gt; (optional, opt-in)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Early warning&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks status&lt;/code&gt; shows schema validation status&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Validation command&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent research validate-schema&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Migration assistant&lt;/strong&gt;: Interactive tool to help map columns&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;These are deferred to assess effectiveness of documentation-based approach first.&lt;/p&gt;</content>
</entry>
