feat: improve sync architecture conformance failure diagnostics (#861)

[prompt-driven-github]

Summary

Improves the diagnostics surfaced when pdd sync hits an architecture conformance failure so reviewers and CI logs see exactly which symbols were missing, which generated file was checked, and how to reproduce locally — instead of the truncated declared symbols missing headline.

Closes #861

Changes Made

Prompts Modified

• pdd/prompts/code_generator_main_python.prompt — Requirement 5 + Architecture Logic instructions get a new sub-bullet mandating that conformance-failure click.UsageError messages contain a stable Architecture conformance error headline followed by a structured block (prompt filename, generated path, missing symbols, AST-detected top-level symbols capped at 50, local repro command). _verify_architecture_conformance gains an optional generated_path parameter; the call site passes output_path.
• pdd/prompts/agentic_sync_runner_python.prompt — Requirement 9a gets a new "conformance pinning" clause: when the headline is detected in stdout/stderr, the runner extracts up to 12 follow-up diagnostic lines (prompt:, generated:, missing:, detected:, repro:) and pins them ahead of the keyword tail. Adds a _extract_conformance_block helper.

Architecture

• architecture.json — minor metadata update reflecting the prompt edits.

Related

• Preventive PR (upstream cause of conformance failures): Guard existing module prompt contracts #862
• Original incident: PDD CLI: structured progress events and progress-aware pdd sync watchdog #843, feat: structured progress events and progress-aware sync watchdog (#843) #849

Review Checklist

• Prompt syntax is valid
• PDD conventions followed
• Diagnostic block format is stable and parseable by the sync runner
• AST-detected symbol cap (50) is reasonable

Next Steps After Merge

1. Regenerate code from modified prompts in dependency order:

   pdd sync code_generator_main
   pdd sync agentic_sync_runner
   pdd sync one_session_sync
   pdd sync durable_sync_runner
   pdd sync prompts
   pdd sync sync_main
   pdd sync agentic_sync
   pdd sync checkup
   pdd sync ci_drift_heal
   pdd sync generate
   pdd sync maintenance
   pdd sync agentic_checkup
   pdd sync pin_example_hack
   pdd sync sync_orchestration
   

2. Run tests to verify functionality (pytest -vv tests/).
3. Verify a forced missing-symbol scenario produces the new structured diagnostic.

---

Created by pdd change workflow

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[prompt-driven-github]

Step 7/8: Review Loop Final Report

PR: #863
Issue: #861
issue_aligned: true
reviewer-status: codex=clean claude=fixer fresh-final=clean
fresh-final-review: clean
max-rounds-reached: false
max-cost-reached: false
max-duration-reached: false

Summary

Primary reviewer is satisfied after reviewing the fixer response.

Per-Reviewer Status

Reviewer	Status
codex	clean
claude	fixer
fresh-final	clean

Findings

Severity	Status	Location	Finding	Required fix	Reviewer
info	fixed	-	No findings remain.	No fix required.	review-loop

Fixer Rationale

• none

Fixes Attempted

• claude: success; changed_files=pdd/agentic_sync_runner.py, pdd/code_generator_main.py; Fix 1 (code_generator_main): added _format_conformance_error helper and rewrote both click.UsageError raises in _verify_architecture_conformance to emit the structured headline + prompt:/generated:/missing:/detected:/repro: block required by the prompt. The function now accepts an optional generated_path kwarg, and the call site passes output_path. Fix 2 (agentic_sync_runner): added the _extract_conformance_block helper and pinned the conformance block immediately after the deterministic failure reason in _sync_one_module's error string, deduping any keyword lines covered by the pinned block; the final-summary loop in run() now also prefers the pinned block within its 500-char window so GitHub/Cloud summaries surface the missing symbol names. Smoke-tested both helpers; the 35 architecture/conformance tests and the 5 error-summary tests pass. Other test failures are pre-existing LLM-API-key environment issues unrelated to these changes.
• claude: success; changed_files=pdd/agentic_sync_runner.py, pdd/code_generator_main.py, pdd/prompts/agentic_sync_runner_python.prompt, pdd/prompts/code_generator_main_python.prompt, tests/test_agentic_sync_runner.py, tests/test_code_generator_main.py; Addressed all three open findings. (1) Replaced the capitalized-only language regex in _format_conformance_error with a known-language lookup that strips both _python (lowercase) and _Python (uppercase) suffixes via _is_known_language, so repro: pdd sync agentic_sync_runner now matches the canonical sync basename. (2) Added regression tests: three new tests in TestVerifyArchitectureConformance covering the structured prompt:/generated:/missing:/detected:/repro: block, lowercase-suffix repro, and generated_path fallback; plus two _sync_one_module tests and two unit tests for _extract_conformance_block covering pinning of the conformance block alongside a ContentSelector failed warning, dedup of overlapping lines, and basic block extraction. (3) Added def:_format_conformance_error to the code_generator_main prompt's selective include and described the helper contract in the deliverables. While building the dedup test I uncovered a real bug — when the conformance block consumed all keyword lines, the stdout/stderr tail fallback re-echoed the same lines — and fixed it by also filtering tails against the pinned-lines set. Also tightened the agentic_sync_runner prompt to require this tail dedup. All targeted tests pass (139/139); pre-existing unrelated cloud-fallback test failures observed before any change were not introduced by this work.