feat: persist per-step telemetry in checkup workflow state (#1709)

[prompt-driven-github]

Summary

Adds per-step telemetry (step_telemetry) to the pdd checkup workflow state, enabling pdd_cloud durable runs to record each CLI step with stable IDs, cost fidelity, status, model, and timestamps — without coupling to internal step numbering.

Closes #1709

Changes Made

Prompts Modified

• pdd/prompts/agentic_checkup_orchestrator_python.prompt — added Requirement 10 describing STEP_ID_MAP, step_telemetry accumulator, _handle_step_result append logic, skipped-step recording, _build_state/_save_state extension, and Step-7 final JSON inclusion

Architecture Updated

• architecture.json — updated _build_state signature to reflect new step_telemetry parameter; added pdd-interface tag

User Stories Added

• user_stories/story__agentic_checkup_orchestrator.md — issue-derived story linked to the prompt
• user_stories/contracts/agentic_checkup_orchestrator.contract.md — machine-checkable contract for the feature

User Stories

• Policy: warn
• user_stories/story__agentic_checkup_orchestrator.md — issue-derived story linked to: agentic_checkup_orchestrator_python.prompt
• user_stories/contracts/agentic_checkup_orchestrator.contract.md — generated machine-checkable contract
• Validation: ✅ all 1 linked story check(s) passed

Review Checklist

• Prompt syntax is valid
• PDD conventions followed
• Documentation is up to date

Next Steps After Merge

1. Regenerate code from modified prompts in dependency order:

   pdd sync agentic_checkup_orchestrator
   pdd sync checkup
   pdd sync checkup_review_loop
   pdd sync agentic_checkup

2. Run tests to verify functionality
3. Deploy if applicable

---

Created by pdd change workflow

[prompt-driven-github]

🚀 Job Queued!

Job ID: i0gI0ULy44locs6yUNsU
Triggered by: @DianaTao
Label: sync

View Live Progress

Budget cap: none

You can add or change a cap by commenting:

/strength 0.7
/pdd budget N
/pdd settings
/pdd stop

Run controls require write access; /pdd settings is read-only.

[prompt-driven-github]

PDD Agentic Sync Progress

Issue: #1710

Mid-run feedback: @DianaTao pending at next step boundary.

Module	Status	Phase	Duration	Cost
agentic_checkup_orchestrator	Failed	-	8m 3s	$1.51

Total cost: $1.51
Paused: agentic_checkup_orchestrator failed

Failed module details

agentic_checkup_orchestrator

│ Total time: 34.65s | Total cost: $0.7571 | Overall status: Failed │
query='implementation of the multi-step orchestrator pipeline and error 
query='implementation of the multi-step orchestrator pipeline and error 
query='implementation of the multi-step orchestrator pipeline and error 
query='implementation of the multi-step orchestrator pipeline and error 
query='implementation of the multi-step orchestrator pipeline and error 
query='implementation of the multi-step orchestrator pipeline and error 
query='implementation of the multi-step orchestrator pipeline and error 
query='implementation of the multi-step orchestrator pipeline and error 
query='implementation of the multi-step orchestrator pipeline and error 
An unexpected error occurred during sync for 'python': Public surface regression
│ python   │ Failed │    $0.7571 │ Public surface regression for               │

=== public surface regression ===
prompt: │
output: /tmp/pdd_job_i0gI0ULy44locs6yUNsU_8kxoew48/pdd/agentic_checkup_orchestrator.py
removed: CHECKUP_STEP_TIMEOUTS, removed:DEFAULT_MAX_RETRIES
signature_changed: _copy_uncommitted_changes
pre surface size: 67
post surface size: 64

To allow this surface change, add a `BREAKING-CHANGE:` directive to
the prompt body. Example: `BREAKING-CHANGE: remove <symbol>` (or
`rename`, `change signature`).

Reproduce locally: pdd sync agentic_checkup_orchestrator

--- env ---
pdd.__file__: /opt/venv/lib/python3.12/site-packages/pdd/__init__.py
pdd --version: pdd, version 0.0.276.dev10
git SHA: cf09b66c2d88fccc5fad755b950979f1a9f9255c
git status: clean
source: site-packages

[DianaTao]

⚠️ Correction needed: STEP_ID_MAP mislabels steps 1–4 (fix before the prompt is regenerated)

The proposed STEP_ID_MAP does not match pdd checkup's actual steps. The real step table is in pdd/agentic_checkup_orchestrator.py (~L2218, TOTAL_STEPS = 8):

internal #	real CLI step (slug)	description	proposed STEP_ID_MAP
1	discover	Discover project structure & tech stack	request_resolved	❌ wrong
2	deps	Audit dependencies	plan_built	❌ wrong
3	build	Run build/compile checks	research	❌ wrong
4	interfaces	Check cross-module interfaces	requirements_clear	❌ wrong
5	test	Run tests	test	✅
6.1	fix	Fix discovered issues	fix	✅
6.2	regression_tests	Write regression tests	regression	✅ ≈
6.3	e2e_tests	Write e2e/integration tests	e2e	✅ ≈
7	verify	Verify fixes + generate final report	verdict	✅ ≈
8	create_pr	Create/push PR	pr_post	✅ ≈

The map borrowed the front-end vocabulary from the generic pdd change 13-step workflow (request_resolved, plan_built, research, requirements_clear) instead of checkup's real steps (discover, deps, build, interfaces).

Why this matters (fix now, not post-release)

1. The telemetry is operator-facing and would be misleading — request_resolved: $0.42 when the step actually ran the build misattributes cost per phase.
2. Requirement 10 says these ids MUST NOT be renamed after release — shipping wrong names means either living with them or breaking the contract later. The fix is free now (prompt-only, not yet regenerated).
3. The CLI already has the right names — the steps table at agentic_checkup_orchestrator.py:2218 already carries stable slugs; STEP_ID_MAP just needs to mirror them.

Corrected map

STEP_ID_MAP = {
    1:   "discover",
    2:   "deps",
    3:   "build",
    4:   "interfaces",
    5:   "test",
    6.1: "fix",
    6.2: "regression_tests",
    6.3: "e2e_tests",
    7:   "verify",
    8:   "create_pr",
}

Simplification worth considering

Since the steps table already holds these exact stable slugs (steps[step_num][1]), STEP_ID_MAP is largely redundant — the telemetry could emit the existing slug directly as step_id, removing a second drift-prone naming table. Either approach is fine; if you keep the explicit map, align it to the slugs above.

Cloud-side mapping (for promptdriven/pdd_cloud#2297)

With the corrected slugs, the cloud maps CLI → its canonical 11-step model as:

• discover, deps, build, interfaces, test → layer1_checks
• fix → fix_attempt
• regression_tests, e2e_tests → validation_after_fix
• verify → verdict_produced
• create_pr → github_rendered
• request_resolved, plan_built → same-named cloud steps
• workspace_prepared, checkpoint_restored, reports_persisted → cloud-only, recorded cloud-side (no CLI equivalent)

🤖 Generated with Claude Code

[prompt-driven-github]

@DianaTao Noted — your feedback will be incorporated at the next step of the run.

[prompt-driven-github]

❌ PDD Execution Failed

Execution failed: PDD command failed with exit code 1.
Output: 4.65s | Total cost: $0.7571 | Overall status: Failed │
query='implementation of the multi-step orchestrator pipeline and error
query='implementation of the multi-step orchestrator pipeline and error
query='implementation of the multi-step orchestrator pipeline and error
query='implementation of the multi-step orchestrator pipeline and error
query='implementation of the multi-step orchestrator pipeline and error
query='implementation of the multi-step orchestrator pipeline and
Cost: $1.5142