fix: resolve 13 red-team CLI bugs (6 P0, 3 P1, 4 P2)

[marklubin]

Closes #62

Summary

Fixes all 13 bugs identified in the red-team sweep (docs/red-team-prioritized-bug-report-2026-03-10.md), organized by priority:

P0 — Trust/Correctness (6 bugs)

• Implement Synix v0.9: multi-provider, concurrent, hybrid search #3 Resolve relative source_dir/build_dir against the pipeline file location, not the caller's cwd
• Time-gap episode chunking #4 Clear pipeline.synix_dir when --build-dir is overridden so snapshots route to the correct .synix/
• ChatGPT full tree export (include_branches=True) #5 Source loader failures now propagate as errors (runner raises, planner reports status="error") instead of silently producing empty builds with exit code 0
• Document retrospective-only provenance limitation #8 Add Layer.level read-only property — fixes synix info crash (AttributeError: 'Source' has no attribute 'level')
• Inference-aware provenance #9 Rewrite info/status to read .synix/ snapshot store and .synix/releases/ instead of legacy build/ paths
• Streaming search results #11 synix diff uses RefStore run history to find previous snapshots instead of checking non-existent legacy build/versions/ directory

P1 — Operator Consistency (3 bugs)

• Implement Synix v0.1 - declarative pipeline for AI conversation exports #1 Planner stores estimated-count placeholders (not raw inputs) so downstream layers see correct cardinality after ReduceSynthesis
• Retrieval API over named search surfaces #10 Standardize invalid ref handling — all inspector commands (list, search, show, lineage) now exit non-zero with [red]Cannot open snapshot[/red] message
• Search result explanations #12 synix clean also removes refs/releases/ ref files, not just release payloads

P2 — Docs/Discoverability (4 bugs)

• Implement Synix v0.1: build system for agent memory #2 Mesh commands honor SYNIX_MESH_ROOT env var via new resolve_mesh_root() helper
• Voice mode / audio transcription support #6 Batch planner tracks DAG cardinality through the dependency graph instead of calling estimate_output_count(1)
• Rich message metadata and non-text content #7 Fix llms.txt — replace unsupported synix diff <ref-a> <ref-b> with actual CLI syntax
• Interactive provenance drill-down from search results #13 Add refs/plans to refs list prefix scan so saved plan refs are visible

New tests (5 files, 17 tests)

• tests/e2e/test_path_resolution.py — absolute-path pipeline, --build-dir override, info/status with .synix/
• tests/e2e/test_source_load_failure.py — build exits non-zero, plan reports error status
• tests/e2e/test_diff_snapshot_era.py — diff across runs, single-run returns None
• tests/e2e/test_invalid_ref_consistency.py — all 4 inspector commands fail consistently on bad refs
• tests/unit/test_info.py — Layer.level property + compute_levels integration

Test plan

• uv run ruff check — all clean
• uv run pytest tests/ -x — 1937 tests pass
• All 6 demo template goldens regenerated and verified
• CI passes

[github-actions]

Note

Architectural Review — Claude Opus | Blind review (docs + diff only)

Summary

This PR is a hardening pass fixing ~10 bugs across path resolution, error handling, legacy code removal, and planning accuracy. Key changes: (1) resolve relative source_dir/build_dir against the pipeline file location instead of cwd, (2) propagate source load failures as errors instead of silently swallowing them, (3) rewrite synix info/status to read from .synix/ snapshot store instead of legacy build/manifest.json, (4) fix DAG-aware cardinality tracking in both plan and batch_runner so N:1 transforms don't inflate downstream counts, (5) add snapshot-era diff support via ref walking, and (6) clean up release refs alongside release data.

Alignment

Strong alignment. The .synix/ migration in info_commands.py and verify_commands.py removes dead reads against build/manifest.json and list_search_outputs, completing the build/release separation described in DESIGN.md §1.5. The path resolution fix ensures pipelines are portable — consistent with Python-first ergonomics (§4.1). Propagating source load failures as hard errors during build (while reporting "error" status during plan) respects the distinction between terraform apply vs terraform plan (§4.4). The cardinality fix in plan.py makes placeholder artifacts match estimate_output_count, which is critical for accurate cache key reasoning and cost estimation (§4.8). The diff refactor walking refs/runs to find previous snapshots is coherent with the immutable snapshot model.

Observations

1. [positive] test_path_resolution.py — comprehensive e2e coverage for the relative-path bug, including --build-dir override and info/status integration. This is the kind of test that prevents regressions in CLI ergonomics.

2. [positive] test_source_load_failure.py — tests both build (nonzero exit, no snapshot committed) and plan (error status in JSON). Excellent edge-case coverage.

3. [concern] diff.py:140-180 — the snapshot-era fallback reconstructs an Artifact from raw dict data with a datetime.now() default for missing created_at. This silently fabricates provenance metadata. A None or sentinel would be more honest given the audit-determinism principle.

4. [concern] diff.py:172 — the from datetime import datetime import is buried inside a nested try block. Minor, but lazy imports in error-handling paths make debugging harder.

5. [question] plan.py:438-441 — placeholder artifacts use label=f"__plan__{layer.name}_{i}" and artifact_type="placeholder". If any downstream code filters or groups by artifact_type, these could leak into real logic. Is there a guard ensuring placeholders never escape the planning phase?

6. [concern] runner.py:171 — changing source load from warning + empty list to raise RuntimeError is correct for build, but the error message doesn't include the source directory path, making debugging harder for users with multiple sources.

7. [positive] clean_commands.py:77-84 — cleaning release refs alongside release data is the right fix. The test coverage (specific release preserves others, clean-all removes ref dir) is thorough.

8. [nit] models.py:83-85 — adding a level property that returns _level is fine, but _level is still directly accessed in info_commands.py via layer._level. The PR should use layer.level consistently now that the property exists.

9. [positive] Golden file updates in templates/ reflect the path resolution change — <CASE_DIR> placeholders replace ./sources, proving the e2e golden tests exercise the new behavior.

10. [question] batch_runner.py:628-631 — the try/except Exception around layer.load() in plan_batch silently defaults to cardinality 1 on failure. This is inconsistent with the new plan.py behavior that reports "error" status. Should plan_batch also surface the error?

Verdict

This is a solid housekeeping PR that removes legacy code paths, fixes real user-facing bugs, and adds strong test coverage — a good incremental step toward a consistent .synix/-native codebase.

Review parameters

• Model: claude-opus-4-6
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 2,142 lines
• Prompt: .github/prompts/claude_review.md
• Timestamp: 2026-03-10T11:39:48Z

[github-actions]

Note

Red Team Review — OpenAI GPT-5.4 | Adversarial review (docs + diff only)

Threat assessment — Moderate risk: mostly bugfixes, but it quietly changes path semantics, CLI behavior, and release/ref cleanup in ways users will depend on.

One-way doors

1. Relative path resolution anchored to pipeline file (src/synix/build/pipeline.py)
   Hard to reverse because users will start writing pipelines assuming source_dir/build_dir are resolved relative to the pipeline file, not CWD. That becomes part of the Python API contract. Safe only if this behavior is documented everywhere pipeline paths are shown and covered for mixed cases (pipeline.py path + CLI overrides + SYNIX_PROJECT/MCP/mesh contexts).

2. clean now deletes release refs (src/synix/cli/clean_commands.py)
   This changes semantics of a documented command. If users/scripts rely on refs surviving cleanup, this is a breaking behavioral contract. Safe only if docs explicitly say release refs are part of “release targets,” and there are tests for refs/list/show after clean.

3. diff contract drift in llms.txt
   Public docs changed from diff <ref-a> <ref-b> to diff [ARTIFACT_ID] --old-build-dir DIR, which is a materially different user model. That is a CLI one-way door if published. Safe only if the actual CLI already matches this and README/docs are updated consistently. Right now it looks inconsistent.

Findings

1. llms.txt command shape changed without corresponding README/docs updates
   llms.txt now advertises a different diff interface than the rest of the project materials. That is exactly how users and downstream agents get trained into the wrong contract. Severity: [warning]

2. src/synix/build/diff.py picks “previous run” by ref iteration order, not snapshot lineage
   It walks refs/runs in reverse sorted order and picks the first OID different from HEAD. That is not the previous build in any principled sense; it is “latest run ref with a different OID.” If refs are rewritten, backfilled, imported, or named oddly, diff targets the wrong snapshot. The design emphasizes provenance and immutable snapshots; this bypasses lineage. Severity: [warning]

3. src/synix/build/diff.py fabricates created_at=datetime.now() when missing
   Silent data fabrication in provenance/audit code is bad. If created_at is absent, you now produce false metadata instead of surfacing incomplete historical data. Severity: [minor]

4. src/synix/build/batch_runner.py does real source loads during planning
   plan_batch() now calls layer.load() on every Source. That couples planning to source I/O and environment state, and can be expensive/unreliable on large datasets or remote-ish sources. Planning should estimate, not execute source ingestion logic. Severity: [warning]

5. src/synix/build/batch_runner.py swallows source load errors and defaults cardinality to 1
   This is worse than failing: it produces plausible-but-wrong batch estimates. A broken source now looks like one artifact, which contaminates all downstream request estimates. Severity: [warning]

6. src/synix/build/plan.py uses placeholder Artifact(...) with minimal fields for downstream planning
   This is a leaky abstraction. If any downstream estimate logic depends on metadata/labels/content shape, cold-plan behavior diverges from warm-plan behavior. You fixed cardinality for ReduceSynthesis, but by introducing fake artifacts you may have created other estimate skew. Severity: [minor]

7. src/synix/cli/info_commands.py guesses .synix via cwd/build then sibling .synix
   This is heuristic-heavy and ignores explicit pipeline configuration. In a repo with multiple projects or nonstandard build dirs, info can report the wrong store. Hidden complexity from filesystem layout assumptions. Severity: [warning]

8. src/synix/cli/build_commands.py and pipeline.py normalize CLI overrides to absolute paths, changing displayed outputs and probably cache keys/receipts indirectly
   This is user-visible behavior drift with potential downstream effects if paths are fingerprinted or shown in receipts/goldens. I don’t see explicit confirmation that path normalization is excluded from cache semantics. Severity: [minor]

9. Mesh root parameterization (src/synix/mesh/config.py, cli/mesh_commands.py) lacks validation/migration handling
   You added SYNIX_MESH_ROOT, but I see no tests for relative env values, unreadable dirs, or coexistence with existing DEFAULT_MESH_ROOT state. For a distributed system feature, moving state roots is not trivial. Severity: [warning]

Missing

• README/website/docs updates for the path-resolution semantic change and clean deleting release refs.
• Tests proving diff chooses the true parent/previous snapshot when there are >2 runs or non-monotonic run refs.
• Tests for plan_batch() on failing/large sources and whether planning remains side-effect free.
• Tests for info/status in multi-project or custom build-dir layouts.
• Validation for SYNIX_MESH_ROOT being relative, unwritable, or malformed.

Verdict — Ship with fixes: the bugfixes are real, but there are contract drifts and brittle heuristics that should be tightened before this becomes user-facing behavior.

Review parameters

• Model: gpt-5.4
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 2,142 lines
• Prompt: .github/prompts/openai_review.md
• Timestamp: 2026-03-10T11:39:51Z

[github-actions]

Note

Architectural Review — Claude Opus | Blind review (docs + diff only)

Summary

This PR is a hardening pass fixing ~10 bugs across path resolution, error handling, legacy code removal, and planning accuracy. Key changes: relative paths now resolve against pipeline file location, source load failures are surfaced properly (hard error in build, error status in plan), synix info/status migrated from legacy manifest.json/build/ to .synix/ snapshot store, diff works across snapshot-era runs, clean removes orphaned release refs, and plan cardinality tracking is DAG-aware so N:1 transforms propagate correct counts downstream.

Alignment

Strong alignment. The .synix/ migration in info_commands.py and verify_commands.py removes references to the legacy ArtifactStore/manifest.json path, completing the build/release separation described in DESIGN.md §1.5. The plan cardinality fix (layer_cardinality dict in batch_runner.py and placeholder artifacts in plan.py) respects the DAG model — ReduceSynthesis producing 1 artifact no longer inflates downstream estimates. Source load failures becoming hard errors in runner.py aligns with "cache keys capture all inputs" — you can't have a valid snapshot if sources failed to load. The snapshot-era diff in diff.py walks refs/runs to find previous snapshots, consistent with immutable snapshots and the ref-based history model.

Observations

1. [positive] test_diff_snapshot_era.py, test_invalid_ref_consistency.py, test_source_load_failure.py, test_path_resolution.py — thorough e2e coverage for each bug. Edge cases (artifact not in previous run, single-run diff returning None, bad source not committing a snapshot) are explicitly tested.

2. [positive] plan.py placeholder artifacts (__plan__ prefix) give downstream layers correct cardinality without materializing real content. Clean approach to cold-build estimation.

3. [concern] diff.py:140-180 — the snapshot-era fallback constructs an Artifact manually from prev_data dict fields. If SnapshotView.get_artifact() ever changes its return shape, this breaks silently. A factory method or shared deserialization function would be safer.

4. [concern] diff.py:155 — for ref_name, oid in reversed(run_refs) assumes iter_refs returns chronologically sorted refs. If ref names aren't lexicographically ordered by time (e.g., different naming schemes), this finds the wrong "previous" run. Worth a comment or assertion.

5. [question] clean_commands.py:84 — when release_name is None, the entire refs/releases/ directory is removed via shutil.rmtree. Is this safe if a concurrent release command is writing? Pre-1.0 this is probably fine, but worth noting.

6. [positive] build_commands.py:166 — pipeline.synix_dir = None after --build-dir override forces recomputation. Simple and correct.

7. [nit] models.py adds a level property returning _level, but info_commands.py still accesses _level directly. The property exists but isn't consistently used within the same PR.

8. [positive] mesh_commands.py — systematic replacement of DEFAULT_MESH_ROOT with resolve_mesh_root() honoring SYNIX_MESH_ROOT env var. Clean testability improvement.

9. [nit] Golden file changes are ~80% of the diff by line count. All are whitespace normalization from the Rich panel padding regex in demo_commands.py plus <CASE_DIR> path resolution. Mechanical but noisy — consider separating golden updates into their own commit.

10. [concern] batch_runner.py:647 — layer_cardinality.get(dep.name, 1) defaults to 1 for unknown deps. If a dependency is a SearchSurface or other non-Source/non-Transform layer, this silently uses 1. The old code had a similar assumption, so this isn't a regression, but the fallback is undocumented.

Verdict

This is a solid incremental step — it completes the .synix/ migration for remaining legacy code paths, fixes real user-facing bugs with proper error handling, and improves plan accuracy for the DAG model, all with strong test coverage.

Review parameters

• Model: claude-opus-4-6
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,279 lines
• Prompt: .github/prompts/claude_review.md
• Timestamp: 2026-03-10T11:47:17Z

[github-actions]

Note

Red Team Review — OpenAI GPT-5.4 | Adversarial review (docs + diff only)

Threat assessment — Medium risk: this is a grab-bag of behavioral fixes, but it quietly changes CLI semantics, path resolution, failure handling, and release cleanup in ways that can break existing workflows.

One-way doors

1. synix diff CLI shape in llms.txt — You changed the documented interface from diff <ref-a> <ref-b> to diff [ARTIFACT_ID] --old-build-dir DIR. That is a public contract change users and docs/LLM tooling will depend on. Safe only if the actual CLI implementation changed to match, docs/README/website are updated consistently, and you explicitly define deprecation/compat behavior.
2. Path resolution semantics for source_dir/build_dir — load_pipeline() now rewrites relative paths against the pipeline file, not cwd. That’s the right default, but it changes meaning for existing pipelines invoked from different directories. Safe only if this behavior is documented and tested against current templates/CLI overrides, with a migration note.
3. clean removing release refs — clean now mutates ref state, not just filesystem outputs. That changes what “clean” means in a way users/scripts may rely on. Safe only if the command help/docs explicitly say refs are deleted and release recovery semantics are defined.

Findings

1. src/synix/build/diff.py — previous-run lookup by “latest run ref with different OID”
   Failure mode: this is not “previous snapshot”; it is “most recent run ref pointing at a different OID.” Re-releases, branch refs, duplicated OIDs, or out-of-order run refs can pick the wrong baseline. It also ignores snapshot parent links, which the data model already has. Severity: [warning]

2. src/synix/build/diff.py — reconstructing Artifact with datetime.now() fallback
   Failure mode: fake timestamps leak into diff output if metadata lacks created_at, making provenance/audit output nondeterministic. For a system that claims auditability, inventing timestamps is the wrong fallback. Severity: [warning]

3. src/synix/build/batch_runner.py — plan_batch() eagerly calls layer.load()
   Failure mode: planning now does real source loading work, potentially expensive file I/O and parsing, and swallows all exceptions by substituting cardinality 1. That gives misleading estimates and makes plan behavior depend on source availability in a non-transparent way. Severity: [warning]

4. src/synix/build/plan.py + runner.py — inconsistent source failure semantics
   Failure mode: plan reports an "error" step and continues; build hard-fails the whole run. That may be intended, but there’s no evidence of CLI/docs updates explaining the distinction. Also downstream planning with errored sources is unclear. Severity: [warning]

5. src/synix/cli/clean_commands.py — deletes refs/releases directory wholesale
   Failure mode: clean -y now removes all release refs without validating that the corresponding release dirs were actually cleaned successfully. Partial failures leave ref/data divergence possible. There’s no transactional behavior. Severity: [warning]

6. src/synix/cli/info_commands.py / verify_commands.py — release discovery by hardcoded filenames
   Failure mode: status only recognizes search.db and context.md. That bakes projection names/layout into UI logic, leaking implementation details and conflicting with the design’s adapter-based release model. New adapters will look invisible/broken. Severity: [warning]

7. src/synix/build/pipeline.py + src/synix/cli/build_commands.py — path override coupling via pipeline.synix_dir = None
   Failure mode: recomputation of synix_dir depends on callers remembering to null it out after overriding build_dir. That’s fragile stateful coupling. One missed call path and artifacts go to the wrong store. Severity: [warning]

8. Template golden outputs across templates/**/golden/*.txt — visibly degraded Rich layout
   Failure mode: tests now bless broken-looking table/panel rendering (│ ... │ collapsed to minimal width). That’s not just cosmetic; it masks formatting regressions instead of fixing rendering. Severity: [minor]

9. tests/e2e/test_invalid_ref_consistency.py claims consistency but omits assertions
   Failure mode: search_invalid_ref_exits_nonzero and lineage_invalid_ref_exits_nonzero don’t assert the message, only exit code. The “consistency” contract is not actually tested. Severity: [minor]

Missing

• README/website/docs updates for the changed diff behavior and path resolution semantics.
• Tests for show/lineage invalid-ref consistency if those code paths changed; this PR only tests some CLI surfaces.
• Tests for clean partial-failure behavior and ref/data consistency.
• Tests proving previous-artifact diff uses the correct predecessor when multiple run refs exist with same/different OIDs.
• Any documentation of the new "error" plan status.

Verdict — Ship with fixes: several changes are reasonable, but the CLI/documentation mismatch, fragile diff predecessor logic, and adapter-leaking release/status logic should be corrected before merge.

Review parameters

• Model: gpt-5.4
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,279 lines
• Prompt: .github/prompts/openai_review.md
• Timestamp: 2026-03-10T11:47:17Z

[github-actions]

Note

Red Team Review — OpenAI GPT-5.4 | Adversarial review (docs + diff only)

Threat assessment — Medium risk: mostly bug-fix territory, but it changes CLI behavior, path resolution, plan semantics, and release/ref cleanup in ways that can silently break existing workflows.

One-way doors

1. synix diff command shape in llms.txt — You changed the documented interface from diff <ref-a> <ref-b> to diff [ARTIFACT_ID] --old-build-dir DIR. That is a public CLI contract users and docs/agents will depend on. Hard to reverse once copied into scripts and prompts. Safe only if the actual CLI implementation changed to match everywhere, docs/README/site are updated, and backward compatibility or deprecation is defined.
2. Canonical path resolution against pipeline file in src/synix/build/pipeline.py — Resolving source_dir/build_dir relative to the pipeline file instead of cwd is probably correct, but it changes user mental model and can break existing projects that relied on cwd-relative behavior. Safe only if explicitly documented and tested for both relative pipeline paths and CLI overrides.
3. clean deleting release refs in src/synix/cli/clean_commands.py — This changes persistence semantics. If users/scripts treated clean as non-destructive to refs, they now lose ref metadata. Safe only if docs say so and release/ref recovery semantics are clear.

Findings

1. llms.txt command contract drift — The diff changes documented synix diff usage, but there is no corresponding CLI diff implementation shown and README/website still talk in ref/snapshot terms. This is design drift in a public interface. Severity: [warning]
2. src/synix/build/diff.py previous-run lookup by lexicographic ref name — The code assumes iter_refs("refs/runs") sorted lexicographically gives run chronology and then picks the latest different OID. That is brittle (run-9 vs run-10, custom names, imported refs). You are encoding ordering semantics into ref names without validating them. Wrong diffs are very plausible. Severity: [warning]
3. src/synix/build/diff.py reconstructing Artifact with partial fields — It synthesizes an Artifact from snapshot JSON and uses datetime.fromisoformat on metadata. That’s an adapter layer leaking storage schema into domain model construction. Any artifact schema drift will break diff in non-obvious ways. Severity: [minor]
4. src/synix/build/pipeline.py mutates loaded pipeline object paths — load_pipeline() now rewrites pipeline.source_dir and pipeline.build_dir in place. That hidden mutation can affect downstream code that expects declared values, not resolved ones. Also inconsistent with “Python-first declaration” if inspection no longer reflects source file values. Severity: [warning]
5. src/synix/build/plan.py placeholder artifact fabrication — Replacing downstream planning inputs with dummy Artifact(...) objects fixes counts, but it may hide transforms that inspect metadata/content shape during planning. You’re smuggling fake domain objects through the planner instead of a dedicated count abstraction. That’s leaky and fragile. Severity: [warning]
6. src/synix/build/batch_runner.py planning loads full sources — plan_batch() now calls layer.load() to count artifacts. For large sources, planning can become expensive and memory-heavy, directly violating dry-run expectations. This will scale badly on big exports. Severity: [warning]
7. src/synix/build/batch_runner.py cardinality math is semantically wrong for multi-input transforms — Summing dependency cardinalities assumes additive input volume. That’s not generally true for DAG nodes with multiple deps, joins, or transforms like reduce/fold/group. “DAG-aware” is overstated. Estimates may be garbage. Severity: [warning]
8. src/synix/cli/clean_commands.py deletes ref files without transactional safety — It removes release directories and refs separately, with no crash-safety. A failure midway can leave orphaned releases or dangling refs. For a build system centered on provenance/refs, this is sloppy state management. Severity: [warning]
9. Golden output churn across templates — Massive snapshot updates are mostly Rich padding normalization. That’s noise-heavy and obscures real behavioral changes. It increases regression blindness. Severity: [minor]
10. Missing consistent invalid-ref handling beyond covered commands — Tests cover list/search/show/lineage, but this PR also touches refs/info/status/release-adjacent flows. Error handling is still piecemeal, not systemic. Severity: [minor]

Missing

• README/website/docs updates for the changed diff behavior and clarified path resolution semantics.
• Tests for batch planning performance/behavior on large sources and multi-dependency transforms.
• Tests for clean crash consistency / partial failure cases.
• Validation that SYNIX_MESH_ROOT paths are absolute/safe and don’t break systemd/service assumptions.
• A dedicated abstraction for plan cardinality instead of fake Artifact placeholders.

Verdict — Ship with fixes: the bug fixes are useful, but the CLI contract drift, fragile diff ordering, and planner/batch estimation shortcuts need cleanup before this calcifies into user-facing behavior.

Review parameters

• Model: gpt-5.4
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,272 lines
• Prompt: .github/prompts/openai_review.md
• Timestamp: 2026-03-10T11:54:48Z

[github-actions]

Note

Architectural Review — Claude Opus | Blind review (docs + diff only)

Summary

This PR is a housekeeping and correctness sweep fixing ~10 discrete bugs: path resolution for relative source_dir/build_dir, source load failure handling (build now fails-fast, plan reports error status), snapshot-era diff lookup, synix clean now removes orphaned release refs, synix info/status migrated off legacy manifest.json/build/ to .synix snapshot store, DAG-aware cardinality tracking in batch planning, consistent --ref error handling across CLI commands, and a Layer.level read-only property. Golden test files are updated for Rich panel padding normalization and absolute path display.

Alignment

Strong alignment. The .synix/ consolidation (info, status, clean, verify commands) completes the build/release separation described in DESIGN.md §1.5 — removing legacy manifest.json and build/search.db code paths. Fail-fast on source load errors (runner.py) respects provenance completeness: a partial build should never produce a snapshot with incomplete lineage. The plan error status and placeholder artifacts for downstream estimation improve the plan() cost estimation contract from §4.8. Content-addressed object store remains the single write path.

Observations

1. [positive] runner.py — source load now raises RuntimeError instead of silently producing empty artifacts. This prevents committing snapshots with broken provenance chains, directly supporting the "provenance chains are complete" principle.

2. [positive] plan.py — placeholder artifacts (__plan__ prefix) for downstream cardinality estimation fix a real bug where ReduceSynthesis(N:1) would propagate N inputs downstream instead of 1. Test TestReduceDownstreamCount covers this explicitly.

3. [positive] clean_commands.py — release ref cleanup prevents dangling refs after synix clean. Test coverage includes targeted cleanup and preservation of unrelated refs.

4. [concern] diff.py lines 140-183 — the snapshot-era fallback reconstructs an Artifact manually from prev_data dict fields. If SnapshotView.get_artifact() ever changes its return shape, this will silently break. Consider extracting a Artifact.from_snapshot_dict() classmethod to centralize this.

5. [concern] diff.py — reversed(run_refs) relies on lexicographic ordering of ref names (e.g., refs/runs/001 < refs/runs/002). The comment documents this assumption, but if run ref naming ever changes to non-sortable IDs, this breaks silently. Worth a note in the ref naming contract.

6. [question] build_commands.py — pipeline.synix_dir = None after --build-dir override forces recomputation, but is there a risk of the old synix_dir being partially initialized before this line runs? The load_pipeline path already sets synix_dir, so this reset seems safe but ordering-dependent.

7. [positive] info_commands.py — full migration from manifest.json/list_search_outputs to SnapshotView + release directory scanning. Removes the last legacy read path from the info command.

8. [positive] Test coverage is thorough: 5 new test files covering diff across runs, invalid ref consistency, path resolution (e2e with mock Anthropic), source load failures, and Layer.level property. Both happy path and edge cases (artifact not in previous run, single-run diff returns None).

9. [nit] batch_runner.py — the except Exception as exc on source load during batch plan is very broad; FileNotFoundError | ValueError would be more precise. Same pattern in the original code, but worth tightening.

10. [nit] Golden file changes are ~90% of the diff by volume but are purely mechanical (Rich padding normalization + absolute path display). The <CASE_DIR> normalization is a good move for CI stability.

11. [positive] mesh/config.py — resolve_mesh_root() centralizes env var lookup, making mesh commands testable without touching ~/.synix-mesh.

Verdict

This is a well-scoped correctness sweep that removes legacy code paths, improves error handling, and strengthens the .synix/-as-single-source-of-truth contract — a solid incremental step for the project.

Review parameters

• Model: claude-opus-4-6
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,272 lines
• Prompt: .github/prompts/claude_review.md
• Timestamp: 2026-03-10T11:54:50Z

[github-actions]

Note

Red Team Review — OpenAI GPT-5.4 | Adversarial review (docs + diff only)

Threat assessment — Medium risk: this PR fixes real regressions, but it also quietly changes CLI behavior, path semantics, and cleanup behavior in ways users will depend on.

One-way doors

1. Pipeline-relative path resolution (src/synix/build/pipeline.py)
   Relative source_dir, build_dir, and per-Source.dir now resolve against the pipeline file, not CWD. That becomes part of the Python API mental model and will break anyone relying on CWD-relative execution. Safe only if docs are updated everywhere and this is declared as the canonical rule for v0.x.

2. clean removing release refs (src/synix/cli/clean_commands.py)
   This changes ref semantics, not just filesystem cleanup. Users/scripts may rely on refs surviving cleanup for audit/history. Safe only if release refs are explicitly defined as transient pointers, and clean semantics are documented in README/CLI docs.

3. synix diff contract drift (llms.txt vs README/DESIGN)
   Public docs used to describe ref-to-ref diff; llms.txt now says artifact diff against old build dir. That’s an API/CLI shape change. Safe only if the actual CLI has changed accordingly and all user-facing docs are updated consistently. Right now they are not.

Findings

1. llms.txt command contract vs README/DESIGN mismatch
   llms.txt changes synix diff <ref-a> <ref-b> to synix diff [ARTIFACT_ID] --old-build-dir DIR, but README still documents ref-based world (refs, snapshots, releases), and the design doc treats refs as first-class. This is user-facing API drift with no coherent migration story. Severity: [warning]

2. src/synix/build/diff.py picks “previous run” by reverse lexicographic ref name
   The code explicitly assumes lexicographic order of refs/runs/* and uses “latest differing OID.” That is brittle: run-10 sorts before run-2, custom ref names break it, and duplicate OIDs can skip intended history. You’re inferring chronology from filenames instead of snapshot ancestry (parent_snapshot_oids exists). Severity: [warning]

3. src/synix/build/batch_runner.py eagerly loads all source artifacts during planning
   plan_batch() now calls layer.load() just to estimate cardinality. For large datasets this is expensive, can hit full file IO twice (plan then build), and can trigger side effects in custom sources. Planning should not require full source materialization. This does not scale to the “10,000 conversations” story. Severity: [warning]

4. src/synix/build/plan.py fabricates placeholder Artifact objects to propagate counts downstream
   This is a leaky hack. Downstream planning now depends on fake artifacts with empty content and synthetic labels. If any planner logic accidentally inspects content/metadata shape, estimates become nonsense. You’re coupling count estimation to runtime model objects instead of a proper cardinality abstraction. Severity: [warning]

5. src/synix/cli/clean_commands.py deletes release refs after deleting release dirs, non-atomically
   If the process dies between filesystem deletion and ref cleanup, refs can point to missing releases or vice versa. There’s no locking or transactionality. Given Synix’s emphasis on refs/snapshots/provenance, sloppy ref mutation is a reliability problem. Severity: [warning]

6. src/synix/cli/info_commands.py swallows errors and guesses .synix location heuristically
   info now probes pipeline.py, cwd/build, then cwd/.synix, suppressing exceptions. That hides misconfiguration and can report on the wrong store if multiple candidates exist. This is exactly the kind of implicit environment dependency that gets users confused. Severity: [minor]

7. Golden output churn shows formatting instability across many templates
   Most template goldens changed because Rich panel padding is now normalized by regex (src/synix/cli/demo_commands.py). That suggests tests are compensating for unstable UI formatting instead of stabilizing rendering. It’s not a product bug, but it’s brittle maintenance debt. Severity: [minor]

Missing

• README / docs updates for the new path resolution rule. This is user-facing and absent.
• Documentation for changed clean semantics around release refs and external targets.
• Tests for concurrent or interrupted cleanup/ref deletion.
• Tests proving “previous run” diff works with nontrivial ref names/orderings; current tests only use run-001, run-002.
• Any doc update reconciling diff behavior across README, DESIGN, website, and llms.txt.

Verdict — Ship with fixes: the bug fixes are legitimate, but the CLI/documentation drift and brittle history/ref logic should be cleaned up before merge to avoid cementing bad semantics.

Review parameters

• Model: gpt-5.4
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,511 lines
• Prompt: .github/prompts/openai_review.md
• Timestamp: 2026-03-10T20:14:47Z

[github-actions]

Note

Architectural Review — Claude Opus | Blind review (docs + diff only)

Summary

This PR fixes a cluster of path resolution, error handling, and legacy-removal bugs across the CLI, planner, runner, diff engine, and info/status commands. It resolves relative paths against pipeline file location, makes source load failures hard errors during build, adds snapshot-era diff support, migrates info/status off legacy manifest.json/build/ to .synix/, fixes plan cardinality propagation through the DAG, and cleans up release refs during synix clean.

Alignment

Strong alignment. The migration of info and status off legacy manifest.json/build/ artifacts toward .synix/ snapshot store completes the build/release separation described in DESIGN.md §1.5 and the Projection Release v2 RFC. Making source load failures halt the build (runner.py) prevents incomplete snapshots from being committed — preserving the "artifacts are immutable and content-addressed" invariant. The plan cardinality fix ensures cache key estimation respects the DAG topology (DESIGN.md §3.3). Path resolution against pipeline file location is necessary for the Python-first design decision (§4.1) — pipelines must be portable.

Observations

1. [positive] runner.py — Source load failures now raise RuntimeError instead of silently producing empty artifact sets. This prevents committing broken snapshots, directly protecting provenance chain completeness.

2. [positive] plan.py — Placeholder artifacts (__plan__ prefix) with estimated_count fix the DAG cardinality propagation bug. ReduceSynthesis → MapSynthesis chains now plan correctly. Well-tested in TestReduceDownstreamCount.

3. [positive] batch_runner.py — layer_cardinality dict propagates actual source counts through the DAG, replacing the broken estimate_output_count(1) pattern. Same fix as plan.py, applied to batch planning.

4. [concern] diff.py — The snapshot-era ref lookup walks reversed(run_refs) assuming lexicographic sort yields chronological order. If run ref names aren't zero-padded or follow inconsistent naming (e.g., run-9 vs run-10), the "most recent previous" logic breaks. The test uses run-001/run-002 which works, but the code comment acknowledges this is lexicographic, not temporal.

5. [concern] diff.py — The Artifact(**kwargs) reconstruction from snapshot data is fragile. If the artifact schema adds required fields, this will break silently. Consider using a factory method or shared deserialization path.

6. [positive] clean_commands.py — Release refs are now cleaned alongside release directories, and external target warnings prevent users from thinking clean removed files it didn't. Good defensive UX.

7. [positive] pipeline.py — Path resolution of source_dir, build_dir, and per-Source dir against filepath.parent is the correct fix. The synix_dir recomputation after resolution is clean.

8. [question] build_commands.py — source_dir is no longer passed to run_pipeline(). Is the source_dir parameter removed from run_pipeline's signature, or is this relying on the pipeline object already having the resolved path? The diff doesn't show the runner's signature change.

9. [positive] info_commands.py — Full rewrite from legacy manifest.json + sqlite3 probing to SnapshotView. The discovery chain (pipeline.py → build_dir convention → .synix sibling) is thorough.

10. [positive] Test coverage is excellent: 5 new test files covering diff across runs, invalid ref handling, path resolution E2E, source load failures, plan cardinality, clean ref cleanup, and Layer.level property. Both happy paths and edge cases.

11. [nit] Golden file changes are entirely Rich panel padding normalization (\s+│\s*$ → │) plus ./sources → <CASE_DIR>/sources. This is the expected consequence of resolving to absolute paths. The regex in demo_commands.py handles the padding variance.

12. [positive] mesh_commands.py — DEFAULT_MESH_ROOT replaced with resolve_mesh_root() honoring SYNIX_MESH_ROOT env var. Clean testability improvement.

13. [nit] models.py — Layer.level property is read-only, which is correct, but the test asserts via try/except rather than pytest.raises.

Verdict

This is a solid hardening PR that fixes real usability bugs, completes the legacy-to-snapshot migration in CLI commands, and ships with thorough test coverage — a good incremental step.

Review parameters

• Model: claude-opus-4-6
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,511 lines
• Prompt: .github/prompts/claude_review.md
• Timestamp: 2026-03-10T20:14:56Z

[github-actions]

Note

Red Team Review — OpenAI GPT-5.4 | Adversarial review (docs + diff only)

Threat assessment — Moderate risk: this PR fixes real inconsistencies, but it also changes path resolution, failure semantics, and cleanup behavior in ways that can silently break existing workflows.

One-way doors

1. Path resolution relative to pipeline file (src/synix/build/pipeline.py, src/synix/cli/build_commands.py)
   Hard to reverse because users will start depending on “relative to pipeline.py” semantics instead of cwd-relative behavior. Safe only if this is explicitly documented as the contract and tested across build/plan/release/info/status consistently.

2. Source load failure now hard-fails builds (src/synix/build/runner.py)
   This is a behavioral contract change. Scripts may currently rely on partial builds with empty sources. Safe only if release notes/docs call out the change and all source types are audited so “missing/empty” vs “corrupt/unreadable” are distinguished intentionally.

3. clean removing release refs (src/synix/cli/clean_commands.py)
   Deleting refs is user-visible state mutation, not just cleanup. If users/scripts depend on release refs surviving target cleanup, this is irreversible once run. Safe only if refs are defined as derived state in docs and cleanup semantics are documented.

Findings

1. src/synix/build/pipeline.py — mutating pipeline object paths during load
   load_pipeline() rewrites pipeline.source_dir, pipeline.build_dir, and each Source.dir in place. That leaks loader behavior into runtime state and can affect fingerprinting/cache behavior if path strings are part of config hashes. Absolute-path normalization can also make builds machine-specific, undermining portability and potentially cache stability. Severity: [warning]

2. src/synix/build/batch_runner.py — plan_batch() eagerly loads sources
   Planning now calls layer.load() for every source. That makes planning do real file I/O and potentially expensive parsing, which is not obviously compatible with “plan” as a dry-run. It also doubles work for large source trees and bakes execution assumptions into planning. Severity: [warning]

3. src/synix/build/batch_runner.py — fallback cardinality of 1 on source load failure
   On source-load exceptions, batch planning logs a warning and assumes one artifact. That produces misleading estimates precisely when the system is already in an error state. Bad plans are worse than failed plans. Severity: [warning]

4. src/synix/cli/clean_commands.py — external target detection via substring check
   _warn_external_targets() treats a target as internal if str(release_path) in target. That is path validation by substring, which is brittle and wrong for similarly prefixed paths or symlinks. You’re making cleanup messaging depend on unsafe path logic. Severity: [minor]

5. src/synix/cli/info_commands.py and src/synix/cli/verify_commands.py — release output discovery only one level deep
   You now enumerate only top-level files in .synix/releases/<name>/. The docs talk about adapters and external targets; release layouts may evolve. This UI logic is now coupled to current filesystem layout and will underreport nested outputs. Severity: [minor]

6. src/synix/build/diff.py — previous snapshot lookup by “most recent run ref with different OID”
   This assumes lexicographic run-ref ordering and that run refs are complete/history-preserving. If refs are pruned, manually edited, or multiple refs point to the same snapshot, diff behavior becomes non-obvious. The design doc emphasizes provenance and immutable snapshots; using mutable refs as version history is weaker than traversing snapshot parents. Severity: [warning]

7. Template goldens across templates/**/golden/*.txt — output formatting visibly degraded
   The panel/table output is now collapsed and ugly (│ Pipeline: ... │ with lost spacing). Maybe this is normalization noise, maybe real UX regression. Given Synix is CLI-first and docs/screenshots depend on stable output, this should not slide through as cosmetic churn. Severity: [minor]

8. README.md + deletion of llms.txt / synix llms
   Public behavior was removed from the repo and CLI, but there is no compensating doc note beyond deleting the README link. If this was user-facing, that’s a removal without migration guidance. Severity: [warning]

Missing

• Documentation updates for the changed semantics of relative path resolution and build hard-failure on source load.
• Tests for whether absolute path normalization changes cache keys/fingerprints across machines.
• Tests for info/status with nested release outputs and external-target receipts.
• Tests for diff_artifact_by_label() using snapshot parent links instead of ref ordering assumptions.
• Any rationale for removing llms.txt generation and the synix llms CLI.

Verdict — Ship with fixes: the bugfixes are valid, but the behavior changes around path resolution, source failure policy, and cleanup need documentation and a couple of design corrections before this calcifies.

Review parameters

• Model: gpt-5.4
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,830 lines
• Prompt: .github/prompts/openai_review.md
• Timestamp: 2026-03-10T20:25:53Z

[github-actions]

Note

Architectural Review — Claude Opus | Blind review (docs + diff only)

Summary

This PR is a housekeeping and correctness sweep: it fixes path resolution so pipelines work when invoked from outside their directory, improves error handling for failed sources and invalid refs, modernizes info/status commands to read from .synix/ instead of legacy build/ artifacts, fixes downstream cardinality estimation in plan and batch_runner, removes the llms.txt generation feature, cleans up release refs during synix clean, and updates all golden test fixtures for Rich panel padding normalization.

Alignment

Strong alignment. The path resolution fix (load_pipeline resolving relative dirs against the pipeline file) is essential for the "Python-first, pipelines are code" bet — pipelines must work regardless of cwd. The info/status migration from legacy build/manifest.json to SnapshotView over .synix/ directly advances the build/release separation principle (DESIGN.md §1.5). Source load failures now raise RuntimeError during build (immutable snapshots should never contain partial state from a broken source), while plan gracefully reports "error" status — correct distinction between planning and execution. The clean command now removes dangling release refs, which tightens the ".synix/ is the single source of truth" invariant.

Observations

1. [positive] src/synix/build/pipeline.py — Resolving source_dir, build_dir, and per-Source dir against filepath.parent is the right fix. This matches how every other build system handles relative paths in build definitions.

2. [positive] src/synix/build/runner.py — Changing source load failure from silent artifacts = [] to raise RuntimeError is correct. A build that silently produces zero artifacts from a missing source would create a misleading snapshot. Aligns with DESIGN.md's immutable snapshot model.

3. [positive] src/synix/build/plan.py — StepPlan(status="error", reason=...) for failed sources is clean. Plan should report problems without crashing. The placeholder artifact generation (__plan__ labels) for downstream estimation fixes a real cardinality propagation bug.

4. [concern] src/synix/build/diff.py — The snapshot-era ref lookup walks reversed(run_refs) to find the previous run. This is O(n) over all run refs. With 10,000+ builds, iter_refs loads all refs then reverses. Not blocking, but worth noting for scale.

5. [concern] src/synix/build/diff.py:160-175 — Reconstructing an Artifact from prev_data dict with manual key extraction is fragile. If the artifact schema adds a field, this will silently drop it. Consider a factory method on Artifact or SnapshotView.

6. [positive] src/synix/cli/clean_commands.py — _warn_external_targets checking receipt.json for out-of-tree paths and warning without deleting them is exactly right UX. Cleaning release refs alongside release directories maintains referential integrity.

7. [question] src/synix/cli/build_commands.py — When --build-dir is overridden, pipeline.synix_dir = None forces recomputation. Is there a risk that downstream code reads synix_dir before synix_dir_for_build_dir re-derives it? The load_pipeline path sets it, but the CLI override happens after.

8. [positive] src/synix/build/batch_runner.py — DAG-aware cardinality tracking via layer_cardinality dict propagating through the build order is cleaner than calling estimate_output_count(1) per dependency. Fixes real misestimates for N:1 transforms.

9. [positive] Tests are thorough: test_diff_snapshot_era.py (214 lines), test_path_resolution.py (306 lines), test_source_load_failure.py, test_invalid_ref_consistency.py, test_info.py, plus extensions to existing test files. Happy paths and edge cases (single run, artifact not in previous run, bad source, invalid refs) are all covered.

10. [nit] Golden file changes are massive but mechanical — Rich panel padding normalization and ./sources → <CASE_DIR>/sources. The demo_commands.py regex for padding collapse (\s+│\s*$ → │) explains all of them.

11. [positive] Removing llms.txt and its CI workflow is reasonable housekeeping — it was an LLM-generated summary requiring an API key in CI, and the README/DESIGN.md serve the same purpose better.

Verdict

This is a solid correctness and consistency sweep that fixes real usability bugs (path resolution, silent failures, stale legacy code paths) while maintaining strong alignment with the .synix/-as-source-of-truth architecture — a good incremental step.

Review parameters

• Model: claude-opus-4-6
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,830 lines
• Prompt: .github/prompts/claude_review.md
• Timestamp: 2026-03-10T20:26:11Z

[github-actions]

Note

Red Team Review — OpenAI GPT-5.4 | Adversarial review (docs + diff only)

Threat assessment — Medium risk: mostly bug-fix territory, but it quietly changes path semantics, CLI surface area, and failure behavior in ways users will depend on.

One-way doors

1. Pipeline-relative path resolution in src/synix/build/pipeline.py
   You are changing how source_dir, build_dir, and per-Source.dir are interpreted: relative to the pipeline file, not the caller’s cwd. That is hard to reverse because users will author pipelines expecting this behavior, and builds/snapshots will land in different locations. Safe to merge only if this is now the documented rule everywhere and all commands consistently honor it.

2. Removal of synix llms and llms.txt (src/synix/cli/main.py, deleted src/synix/cli/llms_commands.py, deleted workflow/file)
   This is a public CLI/API removal, not cleanup. Anyone scripting synix llms now gets a hard break. Safe only if you explicitly intend to drop support, document it in changelog/README, and ideally leave a stub command with deprecation messaging for v0.x.

3. Build now hard-fails on source load errors (src/synix/build/runner.py)
   Previously source failures degraded to empty input; now they abort the build. That’s the right instinct, but it is still a user-visible contract change. Safe only if this is intentional, documented, and consistent across all entrypoints.

Findings

1. src/synix/build/pipeline.py mutates user pipeline objects during load
   It rewrites pipeline.source_dir, pipeline.build_dir, and Source.dir in place to absolute paths. That leaks loader behavior into the domain model and can affect fingerprinting, display output, tests, and any code expecting declared values to remain stable. This violates the Python-first/declarative story by making load context part of the runtime object. Severity: [warning]

2. src/synix/build/pipeline.py + CLI path overrides create inconsistent precedence semantics
   Loader resolves relative paths against pipeline file, then CLI overwrites them with cwd-resolved absolutes. That means the same textual path gets different meaning depending on whether it came from the file or CLI. Maybe intentional, but it is not obvious and will produce “works in file, fails in CLI” confusion. Severity: [warning]

3. src/synix/build/diff.py chooses previous run by lexicographic ref name, not topology or timestamp
   The comment admits this. refs/runs/run-9 vs run-10 or arbitrary names breaks “previous run” selection. This is fragile and can silently diff against the wrong snapshot. Use ref target ancestry or snapshot timestamps, not filename ordering. Severity: [warning]

4. src/synix/build/diff.py reconstructs Artifact from snapshot dict ad hoc
   This is schema-coupled glue code: manual field mapping, optional created_at, assumptions about metadata shape. If artifact schema evolves, diff silently rots. There should be one canonical deserializer for snapshot artifacts. Severity: [minor]

5. src/synix/cli/clean_commands.py preserves release refs after deleting release payloads
   The new comment says this is intentional, but the command still reports “Cleaned” while leaving refs that look live. That creates dangling logical releases whose materialization no longer exists. Users will discover this later via confusing status/list behavior. If refs are preserved, the UX needs to say so explicitly in command output, not a source comment. Severity: [warning]

6. src/synix/cli/info_commands.py status detection is heuristic and cwd-dependent
   It guesses .synix from pipeline.py, cwd/build, then cwd/.synix. This is a brittle environment-dependent search path for a command that should be deterministic. You already have --build-dir on status; info should expose the same explicit boundary instead of guessing. Severity: [minor]

7. Golden outputs across templates now show visibly mangled Rich layout
   The test updates normalize around broken spacing/padding instead of fixing rendering. The snapshots now contain truncated-looking panels and uneven columns. That is not just cosmetic; it degrades CLI usability and suggests the tests are accommodating nondeterministic formatting drift. Severity: [minor]

8. Deletion of llms workflow/file without replacement
   README removed the link, but no docs/changelog note explains why machine-readable project summary support was removed. For a project explicitly targeting agent workflows/MCP, that’s a regression in discoverability. Severity: [minor]

Missing

• A deprecation note or release note for removing synix llms and llms.txt.
• Tests for show/lineage invalid-ref consistency if those code paths were also intended to change; current tests mention regression but diff doesn’t show corresponding handler changes.
• Documentation updates for the new path-resolution rule and build failure semantics.
• Tests around diff behavior with non-numeric/non-lexicographic run refs.
• Tests for release-ref preservation after clean interacting with releases list/show.

Verdict — Ship with fixes: the bug fixes are sensible, but the CLI removal and undocumented semantic changes around path resolution and source failures are not clean enough to merge as-is.

Review parameters

• Model: gpt-5.4
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,806 lines
• Prompt: .github/prompts/openai_review.md
• Timestamp: 2026-03-10T20:29:11Z

[github-actions]

Note

Architectural Review — Claude Opus | Blind review (docs + diff only)

Summary — This PR is a cleanup and correctness batch: it fixes path resolution so relative dirs resolve against the pipeline file (not cwd), hardens error handling for source load failures and invalid refs, replaces the legacy build/manifest.json-based info/status commands with snapshot-store-aware versions, removes the llms.txt generation feature, fixes batch plan cardinality estimation to be DAG-aware, adds snapshot-era diff support, and updates all golden test fixtures for Rich panel padding normalization. It also adds a Layer.level property and a resolve_mesh_root() helper.

Alignment — Strong fit with the vision. Path resolution against the pipeline file (not cwd) is essential for the "Python-first, pipelines are code" model from DESIGN.md §4.1. Promoting source load failures to hard errors in runner.py respects the principle that provenance chains must be complete — silently producing empty layers would create artifacts with broken lineage. The migration of info/status from manifest.json to SnapshotView aligns with the build/release separation in §1.5: .synix/ is the single source of truth, and the legacy build/ code path is being retired. The snapshot-era diff (walking refs/runs) correctly treats snapshots as immutable, content-addressed objects.

Observations

1. [positive] runner.py now raises RuntimeError on source load failure instead of silently continuing with artifacts = []. This prevents committing snapshots with incomplete provenance — directly supports DESIGN.md's "provenance chains are complete" invariant.

2. [positive] plan.py creates proper placeholder artifacts with estimated_count for downstream planning instead of passing inputs through. This fixes the N:1 → downstream cardinality bug (ReduceSynthesis producing 1 artifact, not N). Test TestReduceDownstreamCount covers this precisely.

3. [concern] diff.py line ~160: The Artifact(**kwargs) reconstruction from snapshot data omits parent_labels, meaning the reconstructed artifact won't carry provenance. This is fine for content diffing but could be a latent issue if diff_artifact ever compares provenance fields.

4. [concern] diff.py uses reversed(run_refs) relying on lexicographic ordering of ref names (refs/runs/001, refs/runs/002). If run ref naming isn't strictly zero-padded or monotonically ordered, this could pick the wrong "previous" run. The comment acknowledges lexicographic sort but doesn't validate the assumption.

5. [positive] batch_runner.py now tracks layer_cardinality as a dict propagated through the DAG, fixing the same N:1 estimation bug that plan.py had. Source layers actually load artifacts to count them, with a fallback of 1 on failure.

6. [positive] clean_commands.py adds _warn_external_targets() — reads release receipts to warn about external files that won't be cleaned. Good UX for the release model. The comment about release refs being preserved is accurate and important.

7. [question] info_commands.py _show_build_status tries three discovery paths for .synix/ (pipeline, build_dir convention, direct sibling). The load_pipeline call inside a try/except Exception: pass block could silently mask real errors in the user's pipeline file. Would a narrower exception filter be safer?

8. [positive] Test coverage is thorough: test_diff_snapshot_era.py (214 lines), test_invalid_ref_consistency.py (65 lines), test_path_resolution.py (306 lines), test_source_load_failure.py (94 lines), test_info.py (48 lines), plus additions to existing test files. Both happy paths and edge cases (single run, artifact not in previous run, nonexistent ref) are covered.

9. [nit] Golden file changes are ~90% of the diff by line count. The <CASE_DIR> replacement and Rich padding normalization are test infrastructure fixes, not behavioral changes. The regex in demo_commands.py (\s+│\s*$ → │) is fragile — it assumes │ only appears at line ends in Rich panels.

10. [positive] Mesh commands now use resolve_mesh_root() instead of the module-level DEFAULT_MESH_ROOT constant, honoring SYNIX_MESH_ROOT env var. Clean testability improvement.

11. [nit] The llms.txt removal deletes a CI workflow, CLI command, and the file itself. The README link is also removed. This is clean but the commit message should note this is a deliberate feature removal, not just cleanup.

Verdict — This is a solid hardening PR that fixes real correctness bugs (path resolution, cardinality estimation, error propagation) while retiring legacy code paths in favor of the snapshot-era architecture. Good incremental step.

Review parameters

• Model: claude-opus-4-6
• Context: README.md, DESIGN.md, synix.dev, PR diff
• Diff size: 4,806 lines
• Prompt: .github/prompts/claude_review.md
• Timestamp: 2026-03-10T20:29:21Z