feat: Milestone 10 — CLI generate/inspect/validate commands

[shaypal5]

Summary

• generate: fully wired end-to-end — parses all CLI flags (--recipe, --seed, --mode, --out, --difficulty, --n-accounts/contacts/leads, --horizon-days, --override), calls Generator.from_recipe().generate(), writes bundle via .save()
• inspect: reads manifest.json and prints human-readable summary — recipe, seed, mode, difficulty, motif family, all tables with row counts, task splits, metadata presence
• validate: checks manifest presence, required files (dataset_card.md, feature_dictionary.csv), table row counts vs manifest, SHA-256 hash integrity, task split file presence/counts/hashes, FK constraint integrity across all 10 relationships, leakage detection (unexpected columns in task splits)
• 22 CLI tests: smoke tests, generate integration (both modes), inspect output assertions, validate pass/fail/corrupt-manifest/missing-table scenarios
• Completes v0.4.0 (Milestones 7–10)

Test plan

• 22 CLI tests pass (generate, inspect, validate)
• Full suite: 562 tests passing
• Ruff lint + format clean

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements the Milestone 10 CLI surface area by wiring generate, inspect, and validate to real bundle I/O, plus integration tests covering the new commands.

Changes:

• Implement leadforge generate end-to-end (parse options → generate bundle → save to disk).
• Add inspect summary output based on manifest.json.
• Add validate checks for required artifacts, row counts, hashes, FK integrity, and leakage; expand CLI test suite accordingly.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
leadforge/cli/commands/generate.py	Wires CLI flags to Generator.from_recipe(...).generate() and bundle.save(out).
leadforge/cli/commands/inspect.py	Reads manifest.json and prints a human-readable bundle summary.
leadforge/cli/commands/validate.py	Adds on-disk bundle validation: files present, hashes/row counts, FK checks, leakage checks.
tests/test_cli.py	Replaces stubs with integration tests for generate/inspect/validate behavior.
.agent-plan.md	Updates milestone status/plan notes to reflect M10 completion and M11 next steps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

pr-agent-context report:

No unresolved review comments, failing checks, or actionable patch coverage gaps were found on PR
#16. Treat this PR as all clear unless new signals appear.

Run metadata:

Tool ref: v4
Tool version: 4.0.20
Trigger: commit pushed
Workflow run: 25095854426 attempt 1
Comment timestamp: 2026-04-29T07:15:27.386511+00:00
PR head commit: 99ff9ecd9c4e95a911ab7b986e05e424f07d6711

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

FK validation builds Python set(...)s from entire FK/PK columns (dropna()), which can be very memory-heavy for large bundles. Consider using vectorized membership (e.g., child_series[~child_series.isin(parent_series)] with parent_series.unique()) or chunking to keep peak memory bounded.

Suggested change

	child_vals = set(child_df[fk.child_column].dropna())
	parent_vals = set(parent_df[fk.parent_column].dropna())
	orphans = child_vals - parent_vals
	if orphans:
	sample = list(orphans)[:3]
	errors.append(
	f"FK violation: {fk.child_table}.{fk.child_column} → "
	f"{fk.parent_table}.{fk.parent_column}: "
	f"{len(orphans)} orphan(s), e.g. {sample}"
	child_series = child_df[fk.child_column].dropna()
	parent_values = parent_df[fk.parent_column].dropna().unique()
	orphan_rows = child_series[~child_series.isin(parent_values)]
	orphan_values = orphan_rows.unique()
	if len(orphan_values) > 0:
	sample = orphan_values[:3].tolist()
	errors.append(
	f"FK violation: {fk.child_table}.{fk.child_column} → "
	f"{fk.parent_table}.{fk.parent_column}: "
	f"{len(orphan_values)} orphan(s), e.g. {sample}"

[Copilot]

row_count = _safe_get(info, 'row_count', '?') may return None (or another non-string) if the manifest is malformed, and f"{row_count:>8}" will raise TypeError for values like None. To keep inspect robust against partially-corrupt manifests, coerce to string before formatting (e.g., f"{str(row_count):>8}") or guard None explicitly.

Suggested change

	typer.echo(f" {name:25s} {row_count:>8} rows")
	typer.echo(f" {name:25s} {str(row_count):>8} rows")

[Copilot]

Leakage detection behavior isn’t covered by tests yet (e.g., a task split Parquet containing an extra column should trigger a validation error). Adding a targeted test case would help prevent regressions once the column-detection logic is fixed.

[Copilot]

Leakage detection is currently ineffective: pd.read_parquet(split_path, columns=[]) returns a DataFrame with zero columns, so actual_columns will always be empty and extra will never be detected. Read the Parquet schema/metadata to get column names (e.g., via pyarrow.parquet.ParquetFile(...).schema.names) or read the file without columns=[]/with nrows=0-style approach if supported.

[Copilot]

validate_bundle assumes load_json() returns a dict; if manifest.json parses to a non-object (e.g., list/str), this will raise at manifest.get(...) and crash the CLI (it only catches LeadforgeError). Consider validating isinstance(manifest, dict) up front and returning a clear error like "Malformed manifest: root is not a JSON object".

[Copilot]

pd.read_parquet(abs_path) can raise (corrupt/unsupported parquet, IO errors). Right now that would abort validation instead of returning an error list. Wrap the read in a try/except and append an error like "Failed to read table parquet: ..." so validate_bundle can report failures gracefully.

Suggested change

	df = pd.read_parquet(abs_path)
	try:
	df = pd.read_parquet(abs_path)
	except Exception as exc:
	errors.append(f"Failed to read table parquet {rel_path}: {exc}")
	continue

[Copilot]

Same issue for task splits: pd.read_parquet(abs_path) may raise and currently would crash validation. Consider catching exceptions per split and recording an error so a single bad split file doesn't prevent reporting other problems.

Suggested change

	df = pd.read_parquet(abs_path)
	try:
	df = pd.read_parquet(abs_path)
	except Exception as exc:
	errors.append(f"Task {task_id}/{split}: failed to read parquet file: {exc}")
	continue