csvops 0.4.0.alpha → 0.6.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5a0c00272c2d10751b234384ac50ee8caa90681860906419ccdec7a6e3c110
-  data.tar.gz: 849d377bec9acd507c0fd37a75e823bb9458295e12a31a5000b9ba599084092d
+  metadata.gz: f7db22cb84c1d08c58b473368f9ad37575a217d6293539309277ed2b032a2852
+  data.tar.gz: 124bebc822fefa5d1f71286701959876260c82164067c36ff94b712a0b4cc1b3
 SHA512:
-  metadata.gz: ba96ce18b4e6d2fd8eb018f406c17e7b810010a788a6be1acb51a714b87dad614d822edb97f780e2c745e257bbc68c89266427876fcc4b3fee57fadb29232630
-  data.tar.gz: 378c4a47b96cf210b28f689d9ef0aa1056c95777d3128d4044d8462cf802eeb53ca148062f4244182105e4b760bbf7dcf48d19705f69f18dfb78e3fc2e935413
+  metadata.gz: a8b8dbcfb66073f46f0ecc625267081fbe730e69ef9295f5d2303af6b831a9d71ef564f78f5b44212eb33c4ad7a5fdb78b54fa98e21dd58669e9494a5d3325fb
+  data.tar.gz: 05cbcaa2ca3116ad463413e53600d32a53df0941ceb8873ed22c2ef2d4cfe1afc8f90e44c7ff4400212ebbd5083a2ceb6a983281291436e9478d5087cc98b9ad

data/README.md

@@ -37,22 +37,30 @@ CSV Tool Menu
 2. Extract rows (range)
 3. Randomize rows
 4. Dedupe using another CSV
-5. Exit
+5. Validate parity
+6. Exit
 >
 ```
 
-Select `1` for column extraction, `2` for row-range extraction, `3` for row randomization, or `4` for cross-CSV dedupe.
+Select `1` for column extraction, `2` for row-range extraction, `3` for row randomization, `4` for cross-CSV dedupe, or `5` for parity validation.
 
 ### 3. Follow prompts
 
-Prompt flow:
+Each menu action runs through a dedicated CLI workflow (`interface/cli/workflows/*`) that handles prompts/output and delegates execution to an interface-agnostic application use case.
 
-- CSV file path
-- Separator (`comma`, `tab`, `semicolon`, `pipe`, or `custom`)
-- Optional header filter + column selection
-- Skip blanks (`Y/n`, default `Y`)
-- Preview + confirmation
-- Output destination (`console` or `file`)
+Workflow internals are split into small composable parts:
+
+- `workflows/builders/*` for session construction
+- `workflows/support/*` for shared mapping/dispatch utilities
+- `workflows/presenters/*` for output formatting and summaries
+
+Prompt flow by action:
+
+- `Extract column`: file path, separator, optional header filter + column select, skip blanks, preview/confirm, output destination.
+- `Extract rows (range)`: file path, separator, start row, end row, output destination.
+- `Randomize rows`: file path, separator, headers present, optional seed, output destination.
+- `Dedupe using another CSV`: source/reference files, separators, header modes, key selectors, match options, output destination.
+- `Validate parity`: left/right files, separator, header mode, parity summary, mismatch samples.
 
 ### 4. Example interaction (console output)
 
@@ -123,7 +131,8 @@ Legend: ` ` = prompt/menu, `+` = user input, `-` = tool output
  2. Extract rows (range)
  3. Randomize rows
  4. Dedupe using another CSV
- 5. Exit
+ 5. Validate parity
+ 6. Exit
 +> 4
  CSV file path: /tmp/source.csv
  Source CSV separator:
@@ -160,6 +169,45 @@ Legend: ` ` = prompt/menu, `+` = user input, `-` = tool output
 -Summary: source_rows=5 removed_rows=3 kept_rows=2
 ```
 
+### 8. Parity interaction example
+
+Legend: ` ` = prompt/menu, `+` = user input, `-` = tool output
+
+```diff
+ CSV Tool Menu
+ 1. Extract column
+ 2. Extract rows (range)
+ 3. Randomize rows
+ 4. Dedupe using another CSV
+ 5. Validate parity
+ 6. Exit
++> 5
+ Left CSV file path: /tmp/left.csv
+ Right CSV file path: /tmp/right.csv
+ Choose separator:
+ 1. comma (,)
+ 2. tab (\t)
+ 3. semicolon (;)
+ 4. pipe (|)
+ 5. custom
++Separator choice [1]: 1
+ Headers present? [Y/n]:
+-MISMATCH
+-Summary: left_rows=10 right_rows=10 left_only=2 right_only=2
+-Left-only examples:
+- 4,Dina (count +1)
+-Right-only examples:
+- 4,Dina-Updated (count +1)
+```
+
+### 9. Parity large-file behavior
+
+- Parity uses a streaming count-delta strategy:
+  - Stream left rows and increment row-key counts.
+  - Stream right rows and decrement row-key counts.
+- Exact duplicate semantics are preserved by count deltas per normalized row value.
+- Memory scales with the number of distinct row keys in the parity map, not the total input row count.
+
 ## Testing
 
 Run tests:
@@ -176,7 +224,7 @@ bundle exec rake test
 
 ## Alpha release
 
-Current prerelease version: `0.4.0.alpha`
+Current prerelease version: `0.5.0.alpha`
 
 Install prerelease from RubyGems:
 
@@ -186,7 +234,7 @@ gem install csvops --pre
 
 Release runbook:
 
-- `docs/release-v0.4.0-alpha.md`
+- `docs/release-v0.5.0-alpha.md`
 
 
 ## Architecture

data/docs/architecture.md

@@ -3,14 +3,112 @@
 The codebase follows a DDD-lite layered structure:
 
 - `domain/`: core domain models and invariants (`ColumnSession`, `RowSession`, `RandomizationSession`, and `CrossCsvDedupeSession` aggregates + supporting entities/value objects).
-- `application/`: use-case orchestration (`RunExtraction`, `RunRowExtraction`, `RunRowRandomization`, `RunCrossCsvDedupe`).
-- `infrastructure/`: CSV reading/streaming and output adapters (console/file), plus cross-CSV dedupe adapter.
+- `application/`: use-case orchestration (`RunExtraction`, `RunRowExtraction`, `RunRowRandomization`, `RunCrossCsvDedupe`, `RunCsvParity`).
+- `infrastructure/`: CSV reading/streaming/comparison and output adapters (console/file).
 - `interface/cli/`: menu, prompts, workflows, and user-facing error presentation.
 - `Csvtool::CLI`: entrypoint wiring from command args to interface/application flow.
 
+## Workflow boundary (standardized)
+
+For all interactive domains (`Column Extraction`, `Row Extraction`, `Row Randomization`, `Cross-CSV Dedupe`, `CSV Parity`), the boundary is:
+
+- `interface/cli/workflows/*`: owns prompts, stdout rendering, and user-facing error presentation.
+- `interface/cli/workflows/builders/*`: builds domain sessions/aggregates from prompt results.
+- `interface/cli/workflows/support/*`: shared workflow utilities (error routing, output destination mapping).
+- `interface/cli/workflows/presenters/*`: workflow-level output/summary rendering.
+- `interface/cli/workflows/steps/*`: optional step-pipeline units for complex workflow orchestration.
+- `application/use_cases/*`: interface-agnostic orchestration with request/result style contracts.
+- `domain/*`: invariants and domain policies.
+- `infrastructure/*`: CSV mechanics and output adapters.
+
+Write-boundary rule:
+- Use cases coordinate write paths but do not perform direct file writes.
+- Direct write APIs (`CSV.open`, writable `File.open`, `File.write`, `IO.write`) are infrastructure-only.
+- File output behavior is implemented in `infrastructure/output/*` writer adapters.
+
+Current usage:
+
+- `RunExtractionWorkflow` uses `WorkflowStepPipeline` + `Steps::Extraction::*`.
+- `RunRowExtractionWorkflow` uses `WorkflowStepPipeline` + `Steps::RowExtraction::*`.
+- `RunRowRandomizationWorkflow` uses `WorkflowStepPipeline` + `Steps::RowRandomization::*`.
+- `RunCrossCsvDedupeWorkflow` uses `WorkflowStepPipeline` + `Steps::CrossCsvDedupe::*`.
+- `RunCsvParityWorkflow` uses `WorkflowStepPipeline` + `Steps::Parity::*`.
+
+## Adding New Concepts
+
+Use this checklist when introducing a new capability (for example: a new transformation function, validator, comparer, or exporter).
+
+### 1) Classify the concept first
+
+- `Workflow concept`: interactive flow and prompt sequence.
+- `Domain concept`: business rule/invariant and core vocabulary.
+- `Application concept`: use-case orchestration and request/result contract.
+- `Infrastructure concept`: file/CSV mechanics, streaming, persistence, or external IO.
+
+If it does not clearly fit one layer, split it until each part has one responsibility.
+
+### 2) Add the feature vertically (thin slice)
+
+Implement in this order:
+
+1. `interface/cli/workflows/*`: new workflow entry or new branch in an existing workflow.
+2. `interface/cli/prompts/*`: prompts for user inputs.
+3. `interface/cli/workflows/builders/*`: build domain session/request objects.
+4. `application/use_cases/*`: interface-agnostic use case with `Result` success/failure.
+5. `domain/*`: new entities/value objects/aggregate changes for invariants.
+6. `infrastructure/*`: adapters needed by the use case.
+7. `interface/cli/workflows/presenters/*`: output and summaries.
+
+Keep each step testable on its own before moving to the next.
+
+### 3) Function type patterns
+
+For a new function type, prefer one of these patterns:
+
+- `Transform` (changes output rows/values):
+  - Domain: transformation options/value objects.
+  - Application: orchestrate transform over streamed rows.
+  - Infrastructure: stream reader/writer implementation.
+- `Validate` (checks and reports findings):
+  - Domain: validation policy and finding model.
+  - Application: run checks and return findings in result data.
+  - Presenter: format findings and summary.
+- `Compare` (source vs reference logic):
+  - Domain: mapping/selectors/match options.
+  - Application: compare strategy and stats.
+  - Infrastructure: dual-source readers and selector helpers.
+- `Export` (destination-focused):
+  - Domain: output destination value object.
+  - Application: orchestrate write path only.
+  - Infrastructure: writer adapter.
+
+### 4) Required boundaries and rules
+
+- Workflows do not contain business rules.
+- Use cases do not prompt or print.
+- Domain does not depend on interface or infrastructure.
+- Infrastructure does not own workflow decisions.
+- Shared workflow helpers belong under `workflows/support/*`.
+- Reusable construction logic belongs under `workflows/builders/*`.
+- Rendering/summary formatting belongs under `workflows/presenters/*`.
+
+### 5) Minimum tests for each new concept
+
+- Prompt tests for each new prompt class.
+- Builder tests for each new builder class.
+- Use-case tests for request/result behavior.
+- Workflow behavior tests for prompt + output integration.
+- One end-to-end CLI test for the happy path.
+
+### 6) Naming and structure guidance
+
+- Prefer domain-first names (`RowRange`, `ColumnSelection`, `MatchOptions`) over technical names.
+- Use `Run<Concept>` for use cases and `Run<Concept>Workflow` for workflows.
+- Keep one file per class and mirror structure under `test/csvtool/...`.
+
 ## Domain model
 
-Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, and `Cross-CSV Dedupe`.
+Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, `Cross-CSV Dedupe`, and `CSV Parity`.
 
 ### Cross-CSV Dedupe (Large-file behavior)
 
@@ -37,7 +135,7 @@ Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, an
   - `ExtractionValue`
   - Shared `OutputDestination` (`console` or `file(path)`)
 - Application service:
-  - `Application::UseCases::RunExtraction` orchestrates one extraction request.
+  - `Application::UseCases::RunExtraction` is interface-agnostic and exposes request/result operations.
 - Infrastructure adapters:
   - `Infrastructure::CSV::HeaderReader`
   - `Infrastructure::CSV::ValueStreamer`
@@ -45,6 +143,12 @@ Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, an
   - `Infrastructure::Output::CsvFileWriter`
 - Interface adapters:
   - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunExtractionWorkflow`
+  - `Interface::CLI::Workflows::Builders::ColumnSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::Extraction::*`
+  - `Interface::CLI::Workflows::Presenters::ColumnExtractionPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
   - `Interface::CLI::Prompts::*`
   - `Interface::CLI::Errors::Presenter`
 
@@ -52,6 +156,7 @@ Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, an
 classDiagram
   direction LR
   class MenuLoop
+  class RunExtractionWorkflow
   class Prompts
   class Errors
   class RunExtraction
@@ -64,12 +169,12 @@ classDiagram
   class OutputDestination
   class HeaderReader
   class ValueStreamer
-  class ConsoleWriter
   class CsvFileWriter
 
-  MenuLoop --> RunExtraction : invokes
-  Prompts --> RunExtraction : provides input
-  RunExtraction --> Errors : reports failures
+  MenuLoop --> RunExtractionWorkflow : invokes
+  RunExtractionWorkflow --> Prompts : uses
+  RunExtractionWorkflow --> Errors : reports failures
+  RunExtractionWorkflow --> RunExtraction : calls
   RunExtraction --> ColumnSession : orchestrates
   ColumnSession o-- CsvSource
   ColumnSession o-- ColumnSelection
@@ -79,7 +184,6 @@ classDiagram
   ColumnSession o-- OutputDestination
   RunExtraction --> HeaderReader
   RunExtraction --> ValueStreamer
-  RunExtraction --> ConsoleWriter
   RunExtraction --> CsvFileWriter
 ```
 
@@ -96,14 +200,19 @@ Core DDD structure:
   - `RowRange` (`start_row`, `end_row`) plus row-range validation errors
   - Shared `OutputDestination` (`console` or `file(path)`)
 - Application service:
-  - `Application::UseCases::RunRowExtraction` orchestrates row-range extraction.
+  - `Application::UseCases::RunRowExtraction` is interface-agnostic and exposes request/result operations.
 - Infrastructure adapters:
   - `Infrastructure::CSV::HeaderReader`
   - `Infrastructure::CSV::RowStreamer`
-  - `Infrastructure::Output::CsvRowConsoleWriter`
   - `Infrastructure::Output::CsvRowFileWriter`
 - Interface adapters:
   - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunRowExtractionWorkflow`
+  - `Interface::CLI::Workflows::Builders::RowExtractionSessionBuilder`
+  - `Interface::CLI::Workflows::Presenters::RowExtractionPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::RowExtraction::*`
   - `Interface::CLI::Prompts::*`
   - `Interface::CLI::Errors::Presenter`
 
@@ -111,6 +220,7 @@ Core DDD structure:
 classDiagram
   direction LR
   class MenuLoop
+  class RunRowExtractionWorkflow
   class Prompts
   class Errors
   class RunRowExtraction
@@ -120,19 +230,17 @@ classDiagram
   class OutputDestination
   class HeaderReader
   class RowStreamer
-  class CsvRowConsoleWriter
   class CsvRowFileWriter
-
-  MenuLoop --> RunRowExtraction : invokes
-  Prompts --> RunRowExtraction : provides input
-  RunRowExtraction --> Errors : reports failures
+  MenuLoop --> RunRowExtractionWorkflow : invokes
+  RunRowExtractionWorkflow --> Prompts : uses
+  RunRowExtractionWorkflow --> Errors : reports failures
+  RunRowExtractionWorkflow --> RunRowExtraction : calls
   RunRowExtraction --> RowSession : orchestrates
   RowSession o-- RowSource
   RowSession o-- RowRange
   RowSession o-- OutputDestination
   RunRowExtraction --> HeaderReader
   RunRowExtraction --> RowStreamer
-  RunRowExtraction --> CsvRowConsoleWriter
   RunRowExtraction --> CsvRowFileWriter
 ```
 
@@ -148,12 +256,19 @@ Core DDD structure:
   - `RandomizationOptions` (optional deterministic `seed`)
   - Shared `OutputDestination` (`console` or `file(path)`)
 - Application service:
-  - `Application::UseCases::RunRowRandomization` orchestrates row randomization.
+  - `Application::UseCases::RunRowRandomization` is interface-agnostic and exposes request/result operations.
 - Infrastructure adapters:
   - `Infrastructure::CSV::HeaderReader`
   - `Infrastructure::CSV::RowRandomizer` (external chunked `RAND + sort` + merge)
+  - `Infrastructure::Output::CsvRandomizedRowFileWriter`
 - Interface adapters:
   - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunRowRandomizationWorkflow`
+  - `Interface::CLI::Workflows::Builders::RowRandomizationSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::RowRandomization::*`
+  - `Interface::CLI::Workflows::Presenters::RowRandomizationPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
   - `Interface::CLI::Prompts::*`
   - `Interface::CLI::Errors::Presenter`
 
@@ -161,6 +276,7 @@ Core DDD structure:
 classDiagram
   direction LR
   class MenuLoop
+  class RunRowRandomizationWorkflow
   class Prompts
   class Errors
   class RunRowRandomization
@@ -170,16 +286,19 @@ classDiagram
   class OutputDestination
   class HeaderReader
   class RowRandomizer
+  class CsvRandomizedRowFileWriter
 
-  MenuLoop --> RunRowRandomization : invokes
-  Prompts --> RunRowRandomization : provides input
-  RunRowRandomization --> Errors : reports failures
+  MenuLoop --> RunRowRandomizationWorkflow : invokes
+  RunRowRandomizationWorkflow --> Prompts : uses
+  RunRowRandomizationWorkflow --> Errors : reports failures
+  RunRowRandomizationWorkflow --> RunRowRandomization : calls
   RunRowRandomization --> RandomizationSession : orchestrates
   RandomizationSession o-- RandomizationSource
   RandomizationSession o-- RandomizationOptions
   RandomizationSession o-- OutputDestination
   RunRowRandomization --> HeaderReader
   RunRowRandomization --> RowRandomizer
+  RunRowRandomization --> CsvRandomizedRowFileWriter
 ```
 
 ### Cross-CSV Dedupe
@@ -201,9 +320,15 @@ Core DDD structure:
   - `Infrastructure::CSV::HeaderReader`
   - `Infrastructure::CSV::SelectorValidator`
   - `Infrastructure::CSV::CrossCsvDeduper` (streams source rows while checking membership against reference key set)
+  - `Infrastructure::Output::CsvCrossCsvDedupeFileWriter`
 - Interface adapters:
   - `Interface::CLI::MenuLoop`
   - `Interface::CLI::Workflows::RunCrossCsvDedupeWorkflow`
+  - `Interface::CLI::Workflows::Builders::CrossCsvDedupeSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::CrossCsvDedupe::*`
+  - `Interface::CLI::Workflows::Presenters::CrossCsvDedupePresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
   - `Interface::CLI::Prompts::*`
   - `Interface::CLI::Errors::Presenter`
 
@@ -224,6 +349,7 @@ classDiagram
   class HeaderReader
   class SelectorValidator
   class CrossCsvDeduper
+  class CsvCrossCsvDedupeFileWriter
 
   MenuLoop --> RunCrossCsvDedupeWorkflow : invokes
   Prompts --> RunCrossCsvDedupeWorkflow : provides input
@@ -238,6 +364,61 @@ classDiagram
   RunCrossCsvDedupe --> HeaderReader
   RunCrossCsvDedupe --> SelectorValidator
   RunCrossCsvDedupe --> CrossCsvDeduper
+  RunCrossCsvDedupe --> CsvCrossCsvDedupeFileWriter
+```
+
+### CSV Parity
+
+Core DDD structure:
+
+- Aggregate root: `ParitySession`
+  - Captures one parity check request.
+  - Holds left/right source paths and parity options.
+- Entities:
+  - `SourcePair` (left and right file paths)
+- Value objects:
+  - `ParityOptions` (separator + header mode)
+- Application service:
+  - `Application::UseCases::RunCsvParity` orchestrates parity validation and returns request/result style payloads.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::CsvParityComparator` (streaming count-delta strategy with duplicate-aware semantics)
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunCsvParityWorkflow`
+  - `Interface::CLI::Workflows::Builders::CsvParitySessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::Parity::*`
+  - `Interface::CLI::Workflows::Presenters::CsvParityPresenter`
+  - `Interface::CLI::Workflows::Support::ResultErrorHandler`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class RunCsvParityWorkflow
+  class Prompts
+  class Errors
+  class RunCsvParity
+  class ParitySession
+  class SourcePair
+  class ParityOptions
+  class HeaderReader
+  class CsvParityComparator
+  class CsvParityPresenter
+
+  MenuLoop --> RunCsvParityWorkflow : invokes
+  RunCsvParityWorkflow --> Prompts : uses
+  RunCsvParityWorkflow --> Errors : reports failures
+  RunCsvParityWorkflow --> CsvParityPresenter : renders
+  RunCsvParityWorkflow --> RunCsvParity : calls
+  RunCsvParity --> ParitySession : orchestrates
+  ParitySession o-- SourcePair
+  ParitySession o-- ParityOptions
+  RunCsvParity --> HeaderReader
+  RunCsvParity --> CsvParityComparator
 ```
 
 ## Project layout
@@ -249,15 +430,21 @@ lib/csvtool/domain/column_session/*
 lib/csvtool/domain/row_session/*
 lib/csvtool/domain/row_randomization_session/*
 lib/csvtool/domain/cross_csv_dedupe_session/*
+lib/csvtool/domain/csv_parity_session/*
 lib/csvtool/domain/shared/output_destination.rb
 lib/csvtool/application/use_cases/run_extraction.rb
 lib/csvtool/application/use_cases/run_row_extraction.rb
 lib/csvtool/application/use_cases/run_row_randomization.rb
 lib/csvtool/application/use_cases/run_cross_csv_dedupe.rb
+lib/csvtool/application/use_cases/run_csv_parity.rb
 lib/csvtool/infrastructure/csv/*
 lib/csvtool/infrastructure/output/*
 lib/csvtool/interface/cli/menu_loop.rb
 lib/csvtool/interface/cli/workflows/*
+lib/csvtool/interface/cli/workflows/builders/*
+lib/csvtool/interface/cli/workflows/support/*
+lib/csvtool/interface/cli/workflows/presenters/*
+lib/csvtool/interface/cli/workflows/steps/*
 lib/csvtool/interface/cli/prompts/*
 lib/csvtool/interface/cli/errors/presenter.rb
 test/csvtool/cli_test.rb         # end-to-end workflow tests

data/docs/release-v0.5.0-alpha.md

@@ -0,0 +1,89 @@
+# Release Checklist: v0.5.0-alpha
+
+## 1. Verify environment
+
+```bash
+ruby -v
+bundle -v
+```
+
+Expected:
+- Ruby `3.3.x`
+
+## 2. Install dependencies
+
+```bash
+bundle install
+```
+
+## 3. Run quality checks
+
+```bash
+bundle exec rake test
+```
+
+## 4. Smoke test CLI commands
+
+```bash
+bundle exec csvtool menu
+bundle exec csvtool column test/fixtures/sample_people.csv name
+```
+
+## 5. Smoke test workflows
+
+### Row extraction workflow
+
+Use menu option `2` (`Extract rows (range)`) and verify:
+- headered CSV rows print correctly in console mode
+- out-of-bounds row range shows friendly message
+- file output mode writes expected CSV rows
+
+### Row randomization workflow
+
+Use menu option `3` (`Randomize rows`) and verify:
+- seeded mode is reproducible
+- headered and headerless modes both work
+- file output path writes valid randomized CSV
+
+### Cross-CSV dedupe workflow
+
+Use menu option `4` (`Dedupe using another CSV`) and verify:
+- expected retained rows for headered source/reference files
+- separator/header-mode combinations still work
+- file output mode writes expected deduped CSV
+
+## 6. Build and validate gem package
+
+```bash
+gem build csvops.gemspec
+gem install ./csvops-0.5.0.alpha.gem
+csvtool menu
+```
+
+## 7. Commit release prep
+
+```bash
+git add -A
+git commit -m "chore(release): prepare v0.5.0-alpha"
+```
+
+## 8. Tag release
+
+```bash
+git tag -a v0.5.0-alpha -m "v0.5.0-alpha"
+git push origin main --tags
+```
+
+## 9. Publish gem (optional for alpha)
+
+```bash
+gem push csvops-0.5.0.alpha.gem
+```
+
+## 10. Create GitHub release
+
+Create release `v0.5.0-alpha` with:
+- Use-case file-write boundary cleanup across all workflows
+- New infrastructure file-writer adapters for row randomization and cross-CSV dedupe
+- Final architecture boundary audit with guard test for direct write APIs in use cases
+- Updated architecture diagrams to reflect current writer adapter dependencies

data/docs/release-v0.6.0-alpha.md

@@ -0,0 +1,84 @@
+# Release Checklist: v0.6.0-alpha
+
+## 1. Verify environment
+
+```bash
+ruby -v
+bundle -v
+```
+
+Expected:
+- Ruby `3.3.x`
+
+## 2. Install dependencies
+
+```bash
+bundle install
+```
+
+## 3. Run quality checks
+
+```bash
+bundle exec rake test
+```
+
+## 4. Smoke test CLI commands
+
+```bash
+bundle exec csvtool menu
+bundle exec csvtool column test/fixtures/sample_people.csv name
+```
+
+## 5. Smoke test workflows
+
+### CSV parity workflow
+
+Use menu option `5` (`Validate parity`) and verify:
+- matching files with reordered rows return parity success
+- mismatch files return friendly mismatch summary with sample deltas
+- separator and header-mode selections are respected
+
+### Existing workflows regression pass
+
+Run quick checks for menu options `1-4` and confirm:
+- column extraction still works
+- row-range extraction still works
+- row randomization still works
+- cross-CSV dedupe still works
+
+## 6. Build and validate gem package
+
+```bash
+gem build csvops.gemspec
+gem install ./csvops-0.6.0.alpha.gem
+csvtool menu
+```
+
+## 7. Commit release prep
+
+```bash
+git add -A
+git commit -m "chore(release): prepare v0.6.0-alpha"
+```
+
+## 8. Tag release
+
+```bash
+git tag -a v0.6.0-alpha -m "v0.6.0-alpha"
+git push origin main --tags
+```
+
+## 9. Publish gem
+
+```bash
+gem push csvops-0.6.0.alpha.gem
+```
+
+## 10. Create GitHub release
+
+Create release `v0.6.0-alpha` with:
+- Dedicated CSV parity validation workflow
+- Header/separator parity options
+- Friendly parity mismatch reporting
+- Streaming delta-count parity comparator
+- Parity architecture convergence (session model, workflow steps, presenter, docs)