speckit.analyze: remediate spec gaps and inconsistencies

Cross-artifact analysis identified 1 CRITICAL, 2 HIGH, 9 MEDIUM, and
4 LOW findings. This commit applies concrete remediations:

- Add Phase 11 (tasks T083-T085) for shell completion (FR-019/020/021)
  which had zero coverage in tasks.md
- Expand US10 (Split) from 1 to 4 acceptance scenarios
- Resolve all 11 unanswered edge case questions with dispositions
- Add remove_run() and split_dataset() to library API contract
- Add MigrationResult dataclass to data-model.md
- Make SC-003 measurable (5-second benchmark target)
- Mark Phase 4 (BIDS 2.0) as PROVISIONAL pending schema stabilization
- Update plan.md to reflect actual code structure (_tsv.py, test_cli_common.py)
- Annotate FR-016 as specific application of FR-009

Co-Authored-By: Claude Code 2.1.92 / Claude Opus 4.6 <noreply@anthropic.com>
Entire-Checkpoint: ac75835aa773

Author: yarikoptic

.specify/specs/00-initial-design.md

@@ -192,22 +192,36 @@ A dataset needs to be split — for example, extracting only behavioral data or
 **Acceptance Scenarios**:
 
 1. **Given** a valid dataset, **When** `bids-utils split --suffix bold --output bold-only/` is run, **Then** only BOLD-related files (and required metadata) are extracted and the result is a valid BIDS dataset.
+2. **Given** a valid dataset, **When** `bids-utils split --datatype anat --output anat-only/` is run, **Then** only anatomical files are extracted, `dataset_description.json` is copied, `participants.tsv` is subset to included subjects, and the result is valid.
+3. **Given** a valid dataset, **When** `bids-utils split --suffix bold --dry-run` is run, **Then** the tool lists files that would be extracted without creating any output.
+4. **Given** a dataset with inherited metadata (higher-level `.json` sidecars), **When** `bids-utils split --suffix bold --output bold-only/` is run, **Then** inherited metadata that applies to extracted files is preserved in the output (either copied or segregated to leaf level) so the resolved metadata is unchanged.
 
 ---
 
 ### Edge Cases
 
 - What happens when a rename creates a filename that exceeds OS path length limits?
+  → **Resolution**: Refuse with exit code 2 and a clear error. Covered by FR-011 (refuse invalid state). No extra task needed — implement as a guard in `rename_file()`.
 - How does the tool handle symlinked files (common with git-annex)?
+  → **Resolution**: `_vcs.py` GitAnnex backend handles this. Locked annexed files are symlinks; `git annex` commands operate on them correctly. Covered by T017-T018.
 - What happens when `_scans.tsv` references files that don't exist on disk (dangling references)?
+  → **Resolution**: Warn but do not fail. Dangling references are a pre-existing dataset issue, not caused by bids-utils. Log at `-v` verbosity.
 - How does the tool handle partial datasets (e.g., missing `dataset_description.json`)?
+  → **Resolution**: `BIDSDataset.from_path()` raises an error if no `dataset_description.json` is found. Covered by T013-T014.
 - What happens when a file is locked by git-annex and content is needed for metadata operations?
+  → **Resolution**: For metadata read operations, content is needed. If locked and content unavailable, skip that file with a warning. Covered by T017-T018 (VCS tests should include locked-file scenario).
 - How does aggregation handle `.nwb` files that embed metadata internally?
+  → **Resolution**: Out of scope. bids-utils operates on BIDS sidecar metadata (`.json` files), not on embedded metadata within data files. NWB internal metadata is outside BIDS's inheritance model.
 - What happens when operating on a dataset on a read-only filesystem?
+  → **Resolution**: Operations will fail with a standard OS permission error. No special handling needed — `--dry-run` is always available for read-only inspection.
 - How does the tool handle datasets with both `participants.tsv` and `participants.json`?
+  → **Resolution**: `_participants.py` updates `participants.tsv` only. `participants.json` is a sidecar describing column semantics and does not need updating when rows change. Covered by T023-T024.
 - How does `migrate` handle a field like `IntendedFor` that uses relative paths but the referenced files don't exist (broken references)?
+  → **Resolution**: Convert the path format to BIDS URI regardless — the migration fixes the format, not the referential integrity. Log a warning about the broken reference. Covered by acceptance scenario US2.8 (ambiguous cases skipped with clear reporting).
 - How does `migrate` handle deprecated metadata fields that appear in inherited (higher-level) JSON sidecars vs. leaf-level ones?
+  → **Resolution**: Migrate the field wherever it appears. The inheritance chain is not changed — if `BasedOn` appears in a root-level sidecar, it is renamed to `Sources` there. Covered by T031-T038.
 - What happens when migrating `ScanDate` to `_scans.tsv` but no `_scans.tsv` exists yet for that subject/session?
+  → **Resolution**: Create the `_scans.tsv` with the appropriate header and populate the `acq_time` column. Explicitly covered by T036.
 
 ## Clarifications
 
@@ -237,7 +251,7 @@ A dataset needs to be split — for example, extracting only behavioral data or
 - **FR-013**: System MUST support `-v` / `-q` verbosity controls.
 - **FR-014**: System MUST support `--include-sourcedata` flag for operations that can extend to `sourcedata/` and `.heudiconv/`.
 - **FR-015**: Sidecar discovery MUST handle all BIDS-recognized sidecar extensions (`.json`, `.bvec`, `.bval`, `.tsv` for events, etc.) based on the schema.
-- **FR-016**: `migrate` MUST derive all deprecation knowledge from the `bidsschematools` machine-readable schema (deprecation rules, metadata definitions, enum definitions) — not from hardcoded migration tables.
+- **FR-016**: `migrate` MUST derive all deprecation knowledge from the `bidsschematools` machine-readable schema (deprecation rules, metadata definitions, enum definitions) — not from hardcoded migration tables. *(Specific application of FR-009 to the migration subsystem.)*
 - **FR-017**: `migrate` MUST default to the current released BIDS version when no `--to` target is specified, and MUST support explicit `--to` for both 1.x and 2.0 targets.
 - **FR-018**: `migrate` MUST apply migrations cumulatively — migrating from 1.4 to 1.9 applies all intermediate deprecation fixes in version order.
 - **FR-019**: System MUST provide a `bids-utils completion [SHELL]` subcommand that outputs shell completion activation scripts. When `SHELL` argument is omitted, auto-detect from the `$SHELL` environment variable. Supported shells: Bash, Zsh, Fish (matching Click 8.0+ built-in completion support). Output goes to stdout only (no `--install` flag).
@@ -259,7 +273,7 @@ A dataset needs to be split — for example, extracting only behavioral data or
 
 - **SC-001**: Every bids-examples dataset that is valid before a `rename`/`subject-rename`/`session-rename` operation is still valid after the operation completes.
 - **SC-002**: `--dry-run` output for every command matches the actual changes when run without `--dry-run` (verified by comparing dry-run output to actual filesystem diff).
-- **SC-003**: All commands complete on a 1000-subject dataset within reasonable time (no pathological performance cliffs — O(n) in number of affected files, not O(n²) in total dataset size).
+- **SC-003**: All commands complete on a 1000-subject dataset in O(n) time relative to affected files (not O(n²) in total dataset size). Single-entity operations (rename, remove-run) must not scan the entire dataset. Benchmark target: `rename` on a single file in a 1000-subject dataset completes in under 5 seconds.
 - **SC-004**: Library API is independently usable: all acceptance scenarios can be executed via Python imports without the CLI.
 - **SC-005**: 100% of mutating commands have both `--dry-run` and `--json` modes tested in CI.
 - **SC-006**: Test suite passes against at least 3 different BIDS schema versions (e.g., 1.8, 1.9, 2.0-dev).

.specify/specs/00-initial-design/contracts/library-api.md

@@ -114,6 +114,38 @@ def audit_metadata(
     """Report metadata inconsistencies."""
 ```
 
+### `bids_utils.run`
+
+```python
+def remove_run(
+    dataset: BIDSDataset,
+    subject: str,
+    run: str,
+    *,
+    suffix: str | None = None,
+    task: str | None = None,
+    session: str | None = None,
+    shift: bool = True,
+    dry_run: bool = False,
+    force: bool = False,
+) -> OperationResult:
+    """Remove a run and optionally reindex subsequent runs."""
+```
+
+### `bids_utils.split`
+
+```python
+def split_dataset(
+    dataset: BIDSDataset,
+    target: str | Path,
+    *,
+    suffixes: list[str] | None = None,
+    datatypes: list[str] | None = None,
+    dry_run: bool = False,
+) -> OperationResult:
+    """Extract a subset of a dataset by suffix/datatype filter."""
+```
+
 ### `bids_utils.merge`
 
 ```python

.specify/specs/00-initial-design/data-model.md

@@ -196,4 +196,14 @@ class MigrationFinding:
     proposed_value: Any
     can_auto_fix: bool             # False if human judgment needed
     reason: str | None             # Why it can't be auto-fixed (if applicable)
+
+@dataclass
+class MigrationResult:
+    """Result of migrate_dataset(), extends MigrationPlan with outcome."""
+    plan: MigrationPlan
+    success: bool
+    dry_run: bool
+    applied: list[MigrationFinding]   # Findings that were auto-fixed
+    skipped: list[MigrationFinding]   # Findings requiring human judgment
+    errors: list[str]
 ```

.specify/specs/00-initial-design/plan.md

@@ -64,6 +64,7 @@ src/bids_utils/
 ├── _types.py            # Shared type definitions (PathLike, Entity, etc.)
 ├── _vcs.py              # VCS detection and operations (git mv, git annex, datalad)
 ├── _schema.py           # Schema loading and querying helpers (wraps bidsschematools)
+├── _tsv.py              # Shared TSV read/write utilities (used by _scans.py, _participants.py)
 ├── _scans.py            # _scans.tsv read/write/update operations
 ├── _participants.py     # participants.tsv read/write/update operations
 ├── _sidecars.py         # Sidecar discovery (find all associated files for a BIDS file)
@@ -100,6 +101,8 @@ tests/
 ├── test_run.py          # Run removal tests
 ├── test_vcs.py          # VCS integration tests
 ├── test_cli.py          # CLI smoke tests
+├── test_cli_common.py   # Tests for shared CLI options/decorators
+├── test_tsv.py          # Tests for shared TSV utilities
 └── integration/
     └── test_bids_examples.py  # Sweep tests against bids-examples
 ```

.specify/specs/00-initial-design/tasks.md

@@ -132,6 +132,8 @@
 
 **Note**: Exact 2.0 transformations depend on BIDS 2.0 schema stabilization. This phase may iterate.
 
+**⚠ PROVISIONAL**: Tasks T041-T045 are marked complete but their implementations are necessarily preliminary — they target the current 2.0-dev schema which is not yet finalized. These tasks will likely need re-implementation when the BIDS 2.0 schema stabilizes. Track upstream progress and re-validate.
+
 ---
 
 ## Phase 5: User Story 4 — Rename a Subject (Priority: P2)
@@ -256,7 +258,23 @@
 
 ---
 
-## Phase 11: Polish & Cross-Cutting Concerns
+## Phase 11: Shell Completion (FR-019, FR-020, FR-021)
+
+**Purpose**: `bids-utils completion` subcommand with BIDS-aware completions.
+
+**Independent Test**: Run `bids-utils completion bash | source /dev/stdin`, verify tab-completion offers `sub-*`, `ses-*` directories and entity keys.
+
+### Implementation
+
+- [ ] T083 [P] Implement `src/bids_utils/cli/completion.py`: `bids-utils completion [SHELL]` click command — auto-detect shell from `$SHELL`, output activation script to stdout. Supported: Bash, Zsh, Fish (Click 8.0+ built-in).
+- [ ] T084 Implement BIDS-aware custom completions: filesystem-derived items (`sub-*` directories, `ses-*` directories, BIDS file paths) and entity keys from schema (`task=`, `run=`, `acq=`). Uses `_dataset.py` for dataset root resolution (FR-020: honor `--dataset` or walk up from CWD to `dataset_description.json`).
+- [ ] T085 Write tests for completion in `tests/test_cli.py` or `tests/test_completion.py`: `bids-utils completion --help`, shell detection, activation script output for each shell, BIDS-aware completion produces expected items
+
+**Checkpoint**: `bids-utils completion` outputs working activation scripts with BIDS-aware completions.
+
+---
+
+## Phase 12: Polish & Cross-Cutting Concerns
 
 **Purpose**: Improvements that affect multiple user stories.
 
@@ -285,7 +303,8 @@
 - **Phase 8 (Remove / US7-8)**: Depends on Phase 2
 - **Phase 9 (Merge / US9)**: Depends on Phases 5, 6 (uses subject/session rename)
 - **Phase 10 (Split / US10)**: Depends on Phase 1
-- **Phase 11 (Polish)**: Depends on all desired phases being complete
+- **Phase 11 (Completion / FR-019-021)**: Depends on Phase 1 (uses `_dataset.py`, `_schema.py`)
+- **Phase 12 (Polish)**: Depends on all desired phases being complete
 
 ### Parallel Opportunities After Phase 1
 
@@ -298,6 +317,7 @@ Phase 2 (Rename)  ─→  Phase 3 (Migrate 1.x)  ─→  Phase 4 (Migrate 2.0)
                   ─→  Phase 8 (Remove)
 Phase 7 (Metadata) can start immediately after Phase 1
 Phase 10 (Split) can start immediately after Phase 1
+Phase 11 (Completion) can start immediately after Phase 1
 ```
 
 ### Within Each Phase