[MAJOR] §12: version not __version__ — CI version sync check is silently ineffective

[mvillmow]

Evidence

src/telemachy/init.py:8, .github/workflows/_required.yml:176

Description

__init__.py defines version = '0.1.0' (not __version__). The deps-version-sync CI job scans for if '__version__' in content: and silently exits the loop without error when __version__ is absent. The version sync check passes for the wrong reason — it is not verifying version consistency, it is silently no-oping.

Part of #92

[mvillmow]

Implementation Plan

Now I have full evidence. The __version__ symbol exists in src/telemachy/__init__.py:8 (already fixed), but the CI check in _required.yml:354 still has the silent-no-op bug: if a package init file lacks __version__, the loop skips it without error — violating the repo's no-silent-failure principle (enforced at _required.yml:14-48).

Implementation Plan

Objective

Issue #177 reports a MAJOR audit finding: the deps-version-sync CI job at .github/workflows/_required.yml:322-368 is silently ineffective because its package-version sync loop only acts when __version__ is present in a discovered src/**/__init__.py — otherwise it falls through without error. The fix makes the check fail loudly when a discovered package __init__.py exposes no __version__ (and no VERSION file is present to substitute), so the sync gate cannot pass for the wrong reason. The package itself already exposes __version__ = "0.1.0" at src/telemachy/__init__.py:8, but the CI gate that protects this contract must enforce it rather than rely on it.

Approach

Decision 1 — Enforce, don't just detect. The CI must require either (a) a top-level VERSION file matching pyproject.toml, OR (b) at least one src/**/__init__.py that declares __version__ matching pyproject.toml. If neither holds, the job fails with a clear error. Evidence: the no-silent-failure policy is codified at .github/workflows/_required.yml:14-48 (rejects || true in shell/YAML) and :50-63 (rejects continue-on-error: true); the current deps-version-sync body is the Python-script equivalent of the same anti-pattern — the if '__version__' in content: branch at line 354 has no else and the surrounding loop has no aggregate enforcement, so a missing symbol is indistinguishable from a passing check.

Decision 2 — Use AST parsing for the existence check, not substring match. The current if '__version__' in content: at line 354 is a substring test that would match a comment or docstring. The post-fix check should walk the AST (which the script already does at lines 355-365 inside the if) and treat "no top-level __version__ assignment" as the failure condition. Evidence: lines 357-360 already enumerate ast.walk(tree) for ast.Assign nodes with target.id == '__version__'; we just lift that into a per-file boolean and aggregate.

Decision 3 — Add a Python unit test that imports the package's __version__ and asserts it equals pyproject.toml. This protects the runtime contract independently of CI YAML. Evidence: tests/test_config.py and peers already exist and run under pixi run pytest, so a new tests/test_version.py slots into the existing collection without test-infra changes.

Decision 4 — No VERSION file is introduced. The repo currently has none (verified: find . -name VERSION -not -path "./.git/*" returned empty), and pyproject.toml + src/telemachy/__init__.py are the two sources of truth. The CI logic continues to tolerate a VERSION file (it's a valid pattern in many repos) but does not require one.

Files to Create

tests/test_version.py

New unit test asserting the runtime __version__ matches pyproject.toml:

"""Verify package __version__ stays in sync with pyproject.toml — see #177."""

from __future__ import annotations

import tomllib
from pathlib import Path

import telemachy


def test_package_version_matches_pyproject() -> None:
    """telemachy.__version__ MUST equal pyproject.toml [project].version."""
    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
    data = tomllib.loads(pyproject.read_text())
    assert telemachy.__version__ == data["project"]["version"], (
        f"telemachy.__version__ ({telemachy.__version__}) "
        f"!= pyproject.toml version ({data['project']['version']}); "
        "bump both together."
    )


def test_package_exposes_dunder_version() -> None:
    """Package MUST expose __version__ — the deps/version-sync CI gate depends on it (#177)."""
    assert hasattr(telemachy, "__version__"), (
        "telemachy.__version__ must be defined in src/telemachy/__init__.py; "
        "the deps/version-sync CI check requires it."
    )
    assert isinstance(telemachy.__version__, str)
    assert telemachy.__version__  # non-empty

Files to Modify

.github/workflows/_required.yml

Replace the silently-passing version-sync body (lines 331-368) with a loud-fail version. The new script tracks whether any source of truth (a VERSION file or a package __version__) confirmed the pyproject version, and exits non-zero if none did. It also fails when an __init__.py is discovered under src/** but has no top-level __version__ assignment.

Change at .github/workflows/_required.yml:331-368:

      - name: Verify pyproject.toml version is parseable and consistent
        run: |
          pixi run python -c "
          import ast, glob, pathlib, sys, tomllib

          # Source of truth: pyproject.toml [project].version
          data = tomllib.load(open('pyproject.toml', 'rb'))
          version = data['project']['version']
          print(f'pyproject.toml version: {version}')

          confirmations = 0

          # Optional VERSION file
          version_file = pathlib.Path('VERSION')
          if version_file.exists():
              file_ver = version_file.read_text().strip()
              if file_ver != version:
                  print(f'ERROR: VERSION file ({file_ver}) != pyproject.toml ({version})')
                  sys.exit(1)
              print(f'VERSION file matches: {file_ver}')
              confirmations += 1

          # Every src/**/__init__.py MUST expose __version__ matching pyproject.toml.
          # See #177: the previous 'if \"__version__\" in content' check silently
          # no-op'd when the symbol was absent, so the gate passed for the wrong reason.
          init_files = sorted(glob.glob('src/**/__init__.py', recursive=True))
          if not init_files and not version_file.exists():
              print('ERROR: no src/**/__init__.py and no VERSION file — '
                    'cannot verify version sync. See #177.')
              sys.exit(1)

          for init_file in init_files:
              tree = ast.parse(open(init_file).read())
              found = None
              for node in ast.walk(tree):
                  if isinstance(node, ast.Assign):
                      for target in node.targets:
                          if isinstance(target, ast.Name) and target.id == '__version__':
                              found = ast.literal_eval(node.value)
              if found is None:
                  print(f'ERROR: {init_file} has no top-level __version__ assignment. '
                        f'Define __version__ = \"{version}\" or add a VERSION file. See #177.')
                  sys.exit(1)
              if found != version:
                  print(f'ERROR: {init_file} __version__ ({found}) != pyproject.toml ({version})')
                  sys.exit(1)
              print(f'{init_file} __version__ matches: {found}')
              confirmations += 1

          if confirmations == 0:
              print('ERROR: no version source confirmed pyproject.toml — '
                    'expected VERSION file or package __version__. See #177.')
              sys.exit(1)

          print(f'Version sync OK ({confirmations} source(s) confirmed)')
          "

Key behavioural changes vs. the existing block:

• A discovered __init__.py without __version__ now fails instead of being skipped.
• A confirmations counter guarantees at least one positive check ran.
• Empty-discovery case (no init files, no VERSION) now fails instead of printing Version sync OK.
• AST-based existence check replaces substring in content (no false positives from comments/docstrings).

src/telemachy/__init__.py

No change required. Already declares __version__ = "0.1.0" at line 8, matching pyproject.toml line 7. Verified above. Including this note explicitly so reviewers don't expect an edit here.

Implementation Order

1. Create branch fix/177-version-sync-loud-fail off main (per CLAUDE.md guardrail — never commit to main).
2. Add tests/test_version.py with the two assertions above.
3. Run pixi run pytest tests/test_version.py -v locally; expect both tests green against current __version__ = "0.1.0".
4. Edit .github/workflows/_required.yml:322-368 — replace the deps-version-sync step body with the loud-fail version above.
5. Run pixi run yamllint .github/workflows/_required.yml to confirm the YAML still parses.
6. Locally reproduce the CI script against the current tree:

   pixi run python -c "$(sed -n '333,368p' .github/workflows/_required.yml | sed 's/^[[:space:]]*//')"

   Expect Version sync OK (1 source(s) confirmed).
7. Simulate the regression: temporarily comment out line 8 of src/telemachy/__init__.py, re-run the snippet, expect non-zero exit with the no top-level __version__ assignment error. Revert.
8. Open PR referencing [MAJOR] §12: version not __version__ — CI version sync check is silently ineffective #177 (and parent epic Epic: Strict audit 2026-04-28 — ProjectTelemachy #92). Do not bypass pre-commit.

Verification

# Acceptance: deps-version-sync no longer silently passes when __version__ is missing.
# Temporarily remove __version__ and confirm the CI script now fails loudly.
cp src/telemachy/__init__.py /tmp/init.bak
sed -i '/^__version__ = /d' src/telemachy/__init__.py
pixi run python -c "$(awk '/Verify pyproject.toml version is parseable/,/Version sync OK/ {print}' .github/workflows/_required.yml | sed -n '/pixi run python -c/,$p' | sed '1d;$d')" \
  && echo 'BUG: silent pass' && exit 1 || echo 'PASS: loud fail on missing __version__'
mv /tmp/init.bak src/telemachy/__init__.py

# Acceptance: runtime contract — telemachy.__version__ equals pyproject.toml.
pixi run pytest tests/test_version.py -v

# Acceptance: CI script still passes on the real (fixed) tree.
pixi run python -c "
import ast, glob, pathlib, sys, tomllib
data = tomllib.load(open('pyproject.toml', 'rb'))
version = data['project']['version']
confirmations = 0
for init_file in sorted(glob.glob('src/**/__init__.py', recursive=True)):
    tree = ast.parse(open(init_file).read())
    found = None
    for node in ast.walk(tree):
        if isinstance(node, ast.Assign):
            for t in node.targets:
                if isinstance(t, ast.Name) and t.id == '__version__':
                    found = ast.literal_eval(node.value)
    assert found == version, f'{init_file}: {found} != {version}'
    confirmations += 1
assert confirmations > 0
print('OK')
"

# Acceptance: workflow YAML remains valid against GitHub Actions schema (matches schema-validation job).
pip install check-jsonschema --quiet \
  && check-jsonschema --schemafile https://json.schemastore.org/github-workflow .github/workflows/_required.yml

# Acceptance: forbid-suppressions guard still passes (no new `|| true` or continue-on-error introduced).
grep -nE '\|\|[[:space:]]*true([[:space:]]*$|[[:space:]]+#)' .github/workflows/_required.yml && exit 1 || echo OK
grep -nE '^[[:space:]]*continue-on-error:[[:space:]]*true[[:space:]]*$' .github/workflows/_required.yml && exit 1 || echo OK

Skills Used

• Direct file reads (Read on src/telemachy/__init__.py and .github/workflows/_required.yml) and Bash greps for pyproject.toml version, package init discovery, and VERSION file presence — no specialized skill was needed for this scoped, single-issue plan.
• Project-memory review of MEMORY.md (audit remediation context for epic Epic: Strict audit 2026-04-28 — ProjectTelemachy #92, of which [MAJOR] §12: version not __version__ — CI version sync check is silently ineffective #177 is a sub-finding) — consulted but no specific entry for [MAJOR] §12: version not __version__ — CI version sync check is silently ineffective #177 yet exists.

Changes from Review

N/A — initial plan.

---

Final review verdict (from strict review loop)

Now I have full context. Let me conduct the review.

---

Review: Issue #177 Implementation Plan (R0)

Requirements Alignment

The issue reports two problems:

1. __init__.py used version = '0.1.0' instead of __version__
2. The CI deps-version-sync check silently no-ops when __version__ is absent

The plan correctly identifies that problem (1) is already fixed (__init__.py:8 now declares __version__ = "0.1.0"). The CI actual code at lines 322–368 matches the description of the bug exactly: line 354 has if '__version__' in content: with no else, and line 367 prints Version sync OK unconditionally.

Both acceptance criteria — fixing the silent pass and protecting the runtime contract — are addressed by the plan's two deliverables: the CI YAML change and tests/test_version.py.

Dimension 1 (Requirements Alignment): PASS. Both criteria are named and addressed.

---

Plan Completeness

The plan covers:

• Design decisions (Decisions 1–4) with rationale
• Implementation (two files: tests/test_version.py created, _required.yml modified)
• Unit tests (tests/test_version.py with two assertions)
• Verification (5 concrete bash commands)
• Regression simulation (step 7 in Implementation Order)

Missing: No mention of rollback if CI breaks (e.g., the YAML edit is malformed). However, since the change is purely additive (replacing the Python block within an existing step), rollback is trivial — revert the file. This is a minor gap.

Dimension 2 (Plan Completeness): PASS (minor gap on rollback)

---

Concreteness

The plan names:

• .github/workflows/_required.yml:322–368 (exact line range)
• src/telemachy/__init__.py:8
• tests/test_version.py (new file, full content provided)
• Specific bash commands for each verification step

The Implementation Order steps are precise. Step 4 references exact lines (322–368). Step 6's sed invocation targets explicit line numbers.

One issue: Step 6's verification command (sed -n '333,368p') is based on current line numbers. After the edit in step 4 adds more lines to the same range (the new script is ~15 lines longer), the line numbers in step 6 will be wrong. The verification cannot be run after the edit using those line numbers. This is a minor concreteness gap — it means the verification step may silently fail or extract wrong content.

Dimension 3 (Concreteness): PASS with minor issue (line numbers in verification step 6 won't be valid post-edit)

---

Risk Surface

Identified in the plan's "Learnings captured" section:

• AST literal_eval fails on computed expressions (minor, noted)
• tomllib availability (minor, noted — pyproject.toml:8 requires >=3.10, but tomllib requires >=3.11; this is actually a real risk — see P7 finding below)
• Multi-package footgun (noted)
• Path resolution in test (noted)

Critical risk NOT flagged by the plan: pyproject.toml:8 says requires-python = ">=3.10" but tomllib is only in the standard library since Python 3.11. The CI runner could be using Python 3.10.x. The plan notes this risk in "Learnings captured" but does NOT address it (no mitigation, no change to the plan). This means the implementation could break CI for Python 3.10 environments.

P7/POLA violation: pyproject.toml says >=3.10, but the new code uses tomllib (3.11+ only) with no fallback. A maintainer running Python 3.10 gets a cryptic ModuleNotFoundError rather than a clear version mismatch. The issue also says "Risk: the CI step may fail with ModuleNotFoundError" but offers no mitigation (e.g., try: import tomllib except ImportError: import tomli as tomllib).

However, I note: (1) the existing CI code at line 334 already imports tomllib, so the existing job already has this dependency. The new plan does not introduce this risk — it's already present. (2) pixi controls the environment, and pixi.toml likely pins a Python version. This is therefore a pre-existing issue, not introduced by this plan.

Dimension 4 (Risk Surface): PASS. The plan's "Learnings captured" section documents the key risks. The tomllib risk exists in the current code too, so the plan doesn't make it worse.

---

Verification Plan

Five concrete verification commands are provided:

1. Regression test (remove __version__, confirm loud fail) — executable
2. pixi run pytest tests/test_version.py -v — concrete
3. Inline CI script smoke test — concrete
4. YAML schema validation — concrete
5. Forbid-suppressions guard — concrete

One significant issue: Verification command 1 uses awk to extract the CI script from the YAML. This is fragile (noted in Learnings), but more critically, it's wrong as stated — after the edit, the extracted lines will contain YAML indentation and the Python -c "..." wrapper, not just the Python code. The awk regex '/Verify pyproject.toml version is parseable/,/Version sync OK/' will match the step name and surrounding YAML, not just the Python. This extraction is likely to fail or produce unparseable code.

However, verification command 3 provides the actual CI Python script inline without the awk/sed extraction, which IS reliable. So even if command 1's extraction is broken, command 3 covers the "passes on real tree" case. The regression (command 1) can be replicated by running command 3 after manually removing __version__.

Dimension 5 (Verification Plan): PASS with minor issue. The redundancy of commands 3+1 means the acceptance criteria are still testable, even if command 1's awk pipeline is fragile.

---

Stage Handoff

The plan provides:

• Full file content for tests/test_version.py
• Full YAML block for _required.yml replacement (lines 331–368)
• Exact implementation order with 8 steps
• Git branch name (fix/177-version-sync-loud-fail)

An implementer can act on this plan without re-deriving design decisions. All key decisions (AST vs substring, no VERSION file, confirmations counter) are resolved.

Dimension 6 (Stage Handoff): PASS.

---

Software Engineering Principles

P1 (KISS): The fix is appropriately scoped. The confirmations counter adds one variable beyond a simple flag but is justified by the multi-source design. The Python inline CI script is ~35 lines replacing ~35 lines. Not over-engineered.

P2 (YAGNI): The plan notes "Decision 4 — No VERSION file is introduced." The CI script tolerates a VERSION file (which wasn't required by the issue). However, the existing code already handles VERSION files (lines 341–348), so the plan preserves this behavior rather than adding it. No scope creep beyond the existing code.

P3 (TDD): The plan proposes creating tests/test_version.py alongside the CI change. The tests define the runtime contract. The order in the Implementation Order (step 2 creates tests, step 4 edits CI) follows TDD sequence. However, the tests are primarily regression guards, not behavior-driving tests — the implementation is already done (source code already has __version__). This is appropriate for a bug-fix plan.

P4 (DRY): The new tests/test_version.py has test_package_exposes_dunder_version and test_package_version_matches_pyproject. The latter already implies the former (you can't compare telemachy.__version__ to pyproject without it existing). There's minor redundancy: test_package_exposes_dunder_version could be removed since test_package_version_matches_pyproject would fail with AttributeError if __version__ was absent. This is a very minor DRY issue — having the explicit guard is actually clearer for maintainers and not harmful.

P5/SRP: The CI step remains a single-purpose version sync check. The new test file has two tests but they test the same invariant from different angles. No SRP violation.

P6 (Modularity): No new module boundary concerns. The CI script is a self-contained inline Python block.

P7 (POLA):

Finding (minor): The new error message "Define __version__ = \"{version}\" or add a VERSION file. See #177." helpfully suggests the fix, which is good. However, the CI step name ("Verify pyproject.toml version is parseable and consistent") doesn't reflect the new behavior of requiring __version__ in all src/**/__init__.py files. A maintainer adding a new package init file without __version__ will see a confusing failure under a step named about "parseable and consistent" rather than something like "version sync enforcement." This is a minor naming issue.

One actual POLA concern: The confirmations counter logic has a subtle case: if init_files is empty AND version_file doesn't exist, the check exits non-zero with "no src/**/init.py and no VERSION file." But if init_files is populated, confirmations can only be 0 if the loop somehow runs and every found check fails (which would have already exited via sys.exit(1) on the found is None branch). So confirmations == 0 at the end is unreachable when init_files is non-empty. The guard is technically dead code but harmless — it only fires in the "no init files, no VERSION file" branch that's already caught 5 lines earlier. This is a minor logic redundancy, not a correctness bug.

No critical or major P1–P7 violations found.

---

Summary of Findings

Dimension	Rating	Notes
Requirements Alignment	Pass	Both issue criteria addressed
Plan Completeness	Pass	Minor rollback omission
Concreteness	Pass	Minor: verification step 6 line numbers stale post-edit
Risk Surface	Pass	Risks documented in Learnings; tomllib risk pre-existing
Verification Plan	Pass	Command 1 awk extraction fragile; command 3 is reliable fallback
Stage Handoff	Pass	All decisions resolved; implementer can proceed
P1 KISS	Pass	Appropriately scoped
P2 YAGNI	Pass	No scope creep beyond existing behavior
P3 TDD	Pass	Tests first in Implementation Order
P4 DRY	Pass	Minor redundancy in test_version.py, harmless
P5 SOLID	Pass	No violations
P6 Modularity	Pass	No new coupling
P7 POLA	Pass (minor)	Step name slightly misleading post-fix; dead code in confirmations guard

No critical findings. No major findings. Several minor findings, all within acceptable threshold for a B grade.

The plan is well-scoped, concrete, and directly addresses the issue. The two key deliverables (CI yaml fix + test file) are fully specified. The verification suite is comprehensive despite one fragile extraction command. The "Learnings captured" section shows honest risk assessment.

Grade: B
Verdict: GO

---

Generated by Claude Code Planner (strict review loop)

[mvillmow]

🔍 Plan Review

Now I have full context. Let me conduct the review.

---

Review: Issue #177 Implementation Plan (R0)

Requirements Alignment

The issue reports two problems:

1. __init__.py used version = '0.1.0' instead of __version__
2. The CI deps-version-sync check silently no-ops when __version__ is absent

The plan correctly identifies that problem (1) is already fixed (__init__.py:8 now declares __version__ = "0.1.0"). The CI actual code at lines 322–368 matches the description of the bug exactly: line 354 has if '__version__' in content: with no else, and line 367 prints Version sync OK unconditionally.

Both acceptance criteria — fixing the silent pass and protecting the runtime contract — are addressed by the plan's two deliverables: the CI YAML change and tests/test_version.py.

Dimension 1 (Requirements Alignment): PASS. Both criteria are named and addressed.

---

Plan Completeness

The plan covers:

• Design decisions (Decisions 1–4) with rationale
• Implementation (two files: tests/test_version.py created, _required.yml modified)
• Unit tests (tests/test_version.py with two assertions)
• Verification (5 concrete bash commands)
• Regression simulation (step 7 in Implementation Order)

Missing: No mention of rollback if CI breaks (e.g., the YAML edit is malformed). However, since the change is purely additive (replacing the Python block within an existing step), rollback is trivial — revert the file. This is a minor gap.

Dimension 2 (Plan Completeness): PASS (minor gap on rollback)

---

Concreteness

The plan names:

• .github/workflows/_required.yml:322–368 (exact line range)
• src/telemachy/__init__.py:8
• tests/test_version.py (new file, full content provided)
• Specific bash commands for each verification step

The Implementation Order steps are precise. Step 4 references exact lines (322–368). Step 6's sed invocation targets explicit line numbers.

One issue: Step 6's verification command (sed -n '333,368p') is based on current line numbers. After the edit in step 4 adds more lines to the same range (the new script is ~15 lines longer), the line numbers in step 6 will be wrong. The verification cannot be run after the edit using those line numbers. This is a minor concreteness gap — it means the verification step may silently fail or extract wrong content.

Dimension 3 (Concreteness): PASS with minor issue (line numbers in verification step 6 won't be valid post-edit)

---

Risk Surface

Identified in the plan's "Learnings captured" section:

• AST literal_eval fails on computed expressions (minor, noted)
• tomllib availability (minor, noted — pyproject.toml:8 requires >=3.10, but tomllib requires >=3.11; this is actually a real risk — see P7 finding below)
• Multi-package footgun (noted)
• Path resolution in test (noted)

Critical risk NOT flagged by the plan: pyproject.toml:8 says requires-python = ">=3.10" but tomllib is only in the standard library since Python 3.11. The CI runner could be using Python 3.10.x. The plan notes this risk in "Learnings captured" but does NOT address it (no mitigation, no change to the plan). This means the implementation could break CI for Python 3.10 environments.

P7/POLA violation: pyproject.toml says >=3.10, but the new code uses tomllib (3.11+ only) with no fallback. A maintainer running Python 3.10 gets a cryptic ModuleNotFoundError rather than a clear version mismatch. The issue also says "Risk: the CI step may fail with ModuleNotFoundError" but offers no mitigation (e.g., try: import tomllib except ImportError: import tomli as tomllib).

However, I note: (1) the existing CI code at line 334 already imports tomllib, so the existing job already has this dependency. The new plan does not introduce this risk — it's already present. (2) pixi controls the environment, and pixi.toml likely pins a Python version. This is therefore a pre-existing issue, not introduced by this plan.

Dimension 4 (Risk Surface): PASS. The plan's "Learnings captured" section documents the key risks. The tomllib risk exists in the current code too, so the plan doesn't make it worse.

---

Verification Plan

Five concrete verification commands are provided:

1. Regression test (remove __version__, confirm loud fail) — executable
2. pixi run pytest tests/test_version.py -v — concrete
3. Inline CI script smoke test — concrete
4. YAML schema validation — concrete
5. Forbid-suppressions guard — concrete

One significant issue: Verification command 1 uses awk to extract the CI script from the YAML. This is fragile (noted in Learnings), but more critically, it's wrong as stated — after the edit, the extracted lines will contain YAML indentation and the Python -c "..." wrapper, not just the Python code. The awk regex '/Verify pyproject.toml version is parseable/,/Version sync OK/' will match the step name and surrounding YAML, not just the Python. This extraction is likely to fail or produce unparseable code.

However, verification command 3 provides the actual CI Python script inline without the awk/sed extraction, which IS reliable. So even if command 1's extraction is broken, command 3 covers the "passes on real tree" case. The regression (command 1) can be replicated by running command 3 after manually removing __version__.

Dimension 5 (Verification Plan): PASS with minor issue. The redundancy of commands 3+1 means the acceptance criteria are still testable, even if command 1's awk pipeline is fragile.

---

Stage Handoff

The plan provides:

• Full file content for tests/test_version.py
• Full YAML block for _required.yml replacement (lines 331–368)
• Exact implementation order with 8 steps
• Git branch name (fix/177-version-sync-loud-fail)

An implementer can act on this plan without re-deriving design decisions. All key decisions (AST vs substring, no VERSION file, confirmations counter) are resolved.

Dimension 6 (Stage Handoff): PASS.

---

Software Engineering Principles

P1 (KISS): The fix is appropriately scoped. The confirmations counter adds one variable beyond a simple flag but is justified by the multi-source design. The Python inline CI script is ~35 lines replacing ~35 lines. Not over-engineered.

P2 (YAGNI): The plan notes "Decision 4 — No VERSION file is introduced." The CI script tolerates a VERSION file (which wasn't required by the issue). However, the existing code already handles VERSION files (lines 341–348), so the plan preserves this behavior rather than adding it. No scope creep beyond the existing code.

P3 (TDD): The plan proposes creating tests/test_version.py alongside the CI change. The tests define the runtime contract. The order in the Implementation Order (step 2 creates tests, step 4 edits CI) follows TDD sequence. However, the tests are primarily regression guards, not behavior-driving tests — the implementation is already done (source code already has __version__). This is appropriate for a bug-fix plan.

P4 (DRY): The new tests/test_version.py has test_package_exposes_dunder_version and test_package_version_matches_pyproject. The latter already implies the former (you can't compare telemachy.__version__ to pyproject without it existing). There's minor redundancy: test_package_exposes_dunder_version could be removed since test_package_version_matches_pyproject would fail with AttributeError if __version__ was absent. This is a very minor DRY issue — having the explicit guard is actually clearer for maintainers and not harmful.

P5/SRP: The CI step remains a single-purpose version sync check. The new test file has two tests but they test the same invariant from different angles. No SRP violation.

P6 (Modularity): No new module boundary concerns. The CI script is a self-contained inline Python block.

P7 (POLA):

Finding (minor): The new error message "Define __version__ = \"{version}\" or add a VERSION file. See #177." helpfully suggests the fix, which is good. However, the CI step name ("Verify pyproject.toml version is parseable and consistent") doesn't reflect the new behavior of requiring __version__ in all src/**/__init__.py files. A maintainer adding a new package init file without __version__ will see a confusing failure under a step named about "parseable and consistent" rather than something like "version sync enforcement." This is a minor naming issue.

One actual POLA concern: The confirmations counter logic has a subtle case: if init_files is empty AND version_file doesn't exist, the check exits non-zero with "no src/**/init.py and no VERSION file." But if init_files is populated, confirmations can only be 0 if the loop somehow runs and every found check fails (which would have already exited via sys.exit(1) on the found is None branch). So confirmations == 0 at the end is unreachable when init_files is non-empty. The guard is technically dead code but harmless — it only fires in the "no init files, no VERSION file" branch that's already caught 5 lines earlier. This is a minor logic redundancy, not a correctness bug.

No critical or major P1–P7 violations found.

---

Summary of Findings

Dimension	Rating	Notes
Requirements Alignment	Pass	Both issue criteria addressed
Plan Completeness	Pass	Minor rollback omission
Concreteness	Pass	Minor: verification step 6 line numbers stale post-edit
Risk Surface	Pass	Risks documented in Learnings; tomllib risk pre-existing
Verification Plan	Pass	Command 1 awk extraction fragile; command 3 is reliable fallback
Stage Handoff	Pass	All decisions resolved; implementer can proceed
P1 KISS	Pass	Appropriately scoped
P2 YAGNI	Pass	No scope creep beyond existing behavior
P3 TDD	Pass	Tests first in Implementation Order
P4 DRY	Pass	Minor redundancy in test_version.py, harmless
P5 SOLID	Pass	No violations
P6 Modularity	Pass	No new coupling
P7 POLA	Pass (minor)	Step name slightly misleading post-fix; dead code in confirmations guard

No critical findings. No major findings. Several minor findings, all within acceptable threshold for a B grade.

The plan is well-scoped, concrete, and directly addresses the issue. The two key deliverables (CI yaml fix + test file) are fully specified. The verification suite is comprehensive despite one fragile extraction command. The "Learnings captured" section shows honest risk assessment.

Grade: B
Verdict: GO