feat: make Maestro design workflows faster and resumable

[achuvyas-kv]

Summary

This PR rewrites Maestro's design phase to make PRD, HLD, and LLD generation faster, clearer, resumable, and safer for multi-repository teams.

• Replaces the old PRD brainstorm/subagent flow with a lead-driven clarification interview, deterministic validation, and a single focused writing pass.
• Applies the same interview/writer/validator architecture to HLD and repository-specific LLD generation.
• Splits LLDs into independent repository workstreams so backend, frontend, and mobile teams keep separate state and approvals.
• Adds Approved Corrections: new decisions found after PRD/HLD approval take effect immediately without forcing slow rewrites of every approved document.
• Adds a one-time legacy run upgrade with preview, explicit approval, backups, format conversion, and safe resume behavior.
• Adds structural validators, workflow contracts, tests, documentation, installer updates, and builder support for the new flow.

How the flow is faster

• No PRD subagent spawning: the active lead agent owns clarification and writing, removing agent startup and handoff overhead.
• No global skill search: required Maestro skills are installed by default and resolved from bounded locations.
• Batched questions: each clarification round presents related questions together and records all answers atomically instead of processing one chat answer at a time.
• Clarity before writing: Maestro confirms short project context and feature intent first, then asks only unresolved, decision-relevant questions.
• Incremental interview context: answers are stored as structured context; the model does not repeatedly fold the full conversation into the document.
• One focused document pass: PRD/HLD/LLD writing starts only after blocking gaps are resolved, avoiding premature drafts and repeated full rewrites.
• Deterministic validation: Python validators check required structure and traceability quickly; AI repair is narrow and bounded instead of an open-ended second review pass.
• Approved Corrections instead of rewrites: newly approved decisions become effective immediately and are folded into final design documents once during archive.
• Independent LLD state: each repository resumes and approves its own LLD without being advanced by another team's state file.
• Safe resume and upgrade: compatible runs preserve their exact cursor; legacy runs are upgraded once with backups rather than restarted.

Approved Corrections

When a new requirement or design decision is discovered after the PRD, HLD, or LLD has already been approved, Maestro now offers three explicit choices:

1. Update the approved base design now using the existing revision flow.
2. Approve it as a correction and continue without rewriting the base documents.
3. Reject or defer it.

Choosing Approve as correction creates an immutable correction receipt and immediately adds it to the run's effective design. If a correction conflicts with an older PRD, HLD, or LLD statement, the approved correction wins for all downstream work.

• LLD generation, contracts, test cases, architecture review, implementation, QA, review packs, and retrospectives read the base design plus Approved Corrections.
• Old approved assumptions therefore do not keep returning as false conflicts during later workflow checks.
• Each correction is stored separately, avoiding a shared mutable file when teammates work on different repository branches.
• Recording a repository correction does not advance or overwrite the parent run's state.
• The archive stage folds pending corrections into final PRD/HLD/selected LLD copies once, validates the result, and records the fold.
• Folding is idempotent: rerunning archive does not reapply corrections that were already folded.

Design workflow changes

PRD

• Short project-context and feature-intent confirmation before discovery.
• Native batched question popups with atomic answer recording.
• Focused Grill-style questions driven by unresolved risks and edge cases, not repetitive section checklists.
• Compact, skimmable technical English and concise PRD headers.
• Stable acceptance-criteria IDs for downstream traceability without adding IDs to every section.

HLD and LLD

• Fast clarification-first flow matching the PRD architecture.
• Open questions are resolved before the document is finalized.
• Repository-specific LLD child runs with isolated state and approvals.
• Backend LLD contract includes the data model, migrations, API routes, payloads, errors, authorization, and frontend-consumable behavior.
• Resume always lets the user select or continue the intended LLD workstream.

Legacy run upgrade

• upgrade-run previews whether a run needs migration before making changes.
• Upgrade requires explicit approval and backs up legacy state and design artifacts.
• Compatible current runs preserve their exact workflow cursor.
• Legacy PRD/HLD documents get a bounded one-pass structural conversion when needed.
• Imported legacy LLDs become independent drafts and must pass current validation and human approval.
• Old approvals are never transferred silently.

Validation

• python3 -m unittest discover engine/tests — 221 tests passed.
• python3 testdata/test_ui_schema_sync.py — 4 tests passed.
• python3 testdata/test_workflow_skill_contracts.py — passed.
• python3 engine/maestroctl.py validate workflows/sdlc-main.yaml — 0 errors.
• Full no-LLM SDLC simulation traversed upgrade, design corrections, effective design, implementation, and archive paths.
• A copied real booking legacy run was previewed, upgraded, and resumed successfully while the live run state remained unchanged.