Add functional specification (416 items) and link it from plan/docs

SIMURGARRAY_FUNCTIONAL_SPEC.md defines externally visible behaviour:
CLI, inputs, genotyping outputs, QC and report, cytogenetics CNV/LOH,
targeted PGx copy number, star alleles, methylation control QC, edge-case
catalogue, performance targets, open questions and a traceability table.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01814GKVzZVL3FuF3DeiZXhv

CLAUDE.md

@@ -1,6 +1,8 @@
 # SimurgArray
 Personal research toolkit for Illumina Infinium genotyping arrays (IDAT→GTC→VCF, QC, CN, PGx).
 The full spec and roadmap is SIMURGARRAY_MASTER_PLAN.md — read the relevant section before changing code.
+Externally visible behaviour (CLI options, file schemas, QC semantics, messages, edge cases) is defined item-by-item
+in SIMURGARRAY_FUNCTIONAL_SPEC.md (IDs like CLI-021, OUT-031); cite item IDs in commits and tests.
 
 ## Rules
 - Work phase by phase (§18). Don't start a phase until the previous gate passes.

README.md

@@ -3,7 +3,8 @@
 Personal research toolkit for Illumina Infinium genotyping BeadChip data
 (IDAT → normalization → genotype calling → BAF/LRR → QC → VCF/PLINK; later CN/LOH, PGx, cluster training).
 
-Start with **SIMURGARRAY_MASTER_PLAN.md** (full specification and roadmap).
+Start with **SIMURGARRAY_MASTER_PLAN.md** (architecture, algorithms, roadmap) and
+**SIMURGARRAY_FUNCTIONAL_SPEC.md** (416 itemised requirements: CLI, inputs, outputs, QC, CN, PGx, methylation, edge cases).
 
 ```bash
 bash scripts/bootstrap_refs.sh     # clone reference open-source repos into refs/

SIMURGARRAY_MASTER_PLAN.md

@@ -44,6 +44,10 @@
 
 ## 0. How to use this document
 
+- **Detailed functional specification:** `SIMURGARRAY_FUNCTIONAL_SPEC.md` is the authoritative spec for externally
+  visible behaviour: CLI options, validation, file schemas, QC semantics, messages, edge cases and acceptance tests.
+  Each of its items has an ID and is traced to a § and phase of this plan. This plan remains authoritative for
+  algorithms and numerics.
 - Work **phase by phase** (§18). Do not start a phase before the previous phase's acceptance criteria pass.
 - Every algorithm in §7 is written as exact math with its **evidence source** in brackets:
   **[DOC]** Illumina public documentation / tech notes · **[LIT]** papers & expired patents ·
@@ -684,6 +688,14 @@ per MAF bin; rare-variant performance compared with zCall-style rescue.
 
 ## 13. SimurgArray output specification
 
+> **See `SIMURGARRAY_FUNCTIONAL_SPEC.md` §4 and §6–§9** (items OUT-*, QC-*, CYTO-*, PCN-*, PGX-*, MET-*) for the
+> exact schemas, headers and column orders. Where file names below differ from the spec, the spec wins:
+> - `<sample>.snv.vcf.gz`, `<sample>.cyto.cnv.vcf.gz`, `<sample>.pgx_cn.vcf.gz`;
+> - `<sample>.cyto.json` and `<sample>.pgx.json`;
+> - `controls_raw.tsv` and `controls_qc.tsv`, written by `genotype` itself;
+> - `qc_report_YYYY_MM_DD.html` and `qc_table_YYYY_MM_DD.xlsx`;
+> - the PGx batch TSVs.
+
 Per sample (in `<out>/samples/<sample>/`):
 | File | Content |
 |---|---|
@@ -708,6 +720,15 @@ Per batch (in `<out>/`):
 
 ## 14. CLI specification (`simurg`)
 
+> **See `SIMURGARRAY_FUNCTIONAL_SPEC.md` §2–§3** (items CLI-*, IN-*) for:
+> - the full command tree, and every option with its type, default and validation;
+> - precedence (CLI > YAML > profile > defaults);
+> - the `--log-json` schema and the message-code catalogue;
+> - overwrite/resume policy and exit codes (adds 4 = no sample succeeded, and 130/143 = interrupted);
+> - sample-sheet and input validation rules.
+>
+> The summary below is kept for orientation.
+
 ```
 simurg inspect   <file>                                  # print header/TOC of IDAT/BPM/EGT/GTC
 simurg ingest    --idats DIR|--sheet F --bpm F [--csv F] --out DIR          # → sample_intensity parquet