PlantAI-dev/.superpowers/sdd/task-1-brief.md

Task 1 Brief: Reusable local alias evidence parser

Read this first. It is the binding task specification.

Objective

Create a small reusable, offline parser for job-local reference alias evidence. Do not change PPI execution yet.

Files

• Create gfa_core/id_resolution.py.
• Create tests/unit/test_id_resolution.py.
• Write the implementation report to .superpowers/sdd/task-1-report.md.

Required interfaces

• IdResolutionError for invalid/mismatched/ambiguous evidence.
• Immutable IdAliasCandidate(value: str, namespace: str, method: str, evidence_source: str).
• ReferenceAliasIndex.from_tsv(path: Path, species: str) -> ReferenceAliasIndex.
• ReferenceAliasIndex.candidates(raw_id: str) -> list[IdAliasCandidate].
• Consume legacy columns species_code, protein_id, pep_id, cds_id, gene_id, cds_header; optionally consume ncbi_gene_id.
• Extract numeric NCBI GeneID from [db_xref=GeneID:<digits>] when the explicit column is absent.
• Candidate order for the legacy XP example must be versioned protein accession, numeric GeneID, then LOC gene symbol.
• Exact versioned accessions are primary.
• A versionless lookup is valid only if every matching version converges on the same alias entity; otherwise raise/report ambiguity rather than choosing.
• Any non-empty row whose species_code differs from the declared species invalidates the whole file.
• Deduplicate identical aliases deterministically.
• No online queries and no substring-similarity inference.

Mandatory TDD cycle

1. Write focused tests first.
2. Run /home/xia-lab/miniconda3/envs/test4py311/bin/python -m pytest tests/unit/test_id_resolution.py -q and record the expected RED failure.
3. Implement the minimum code.
4. Run the same command and record GREEN.

Tests must cover:

• Legacy header XP_021867507.1 / LOC110806180 / GeneID:110806180 and versionless lookup.
• Declared species mismatch.
• Mixed-species rows.
• Versionless collision with conflicting GeneIDs.
• Duplicate accession rows with the same GeneID deduplicate cleanly.
• Missing file or unusable required columns produce a structured error.

Global constraints

• Preserve canonical member IDs; this parser only returns aliases.
• Ortholog relationships are not aliases.
• Evidence stays species-scoped and job-local.
• Keep the implementation small and standard-library-only.
• Do not edit files outside this task.
• The workspace has no Git metadata: do not commit.

Report contract

Write .superpowers/sdd/task-1-report.md containing:

• status: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, or BLOCKED;
• files changed;
• RED command and observed failure;
• GREEN command and exact pass count;
• self-review findings;
• concerns or remaining risks.

Return only the status, one-line test summary, and concerns in your final message.