PBI-001: Validate the macOS release workflow and persistence contract for the latest ScopeSmith CLI

[SamMRoberts]

Initiative

• initiative_title: Test and Validate latest ScopeSmith CLI release
• summary: Validate the latest ScopeSmith CLI release on local macOS so the required command workflow behaves correctly end to end, required release artifacts are persisted in the expected session directory, and release confidence is backed by explicit automated and manual evidence.

Context

Desired outcome: all required commands result in the expected workflow state changes, AI-backed interactions, and local artifact creation, and the full test suite passes in a local macOS development environment.

Hard requirements

• new
• generate
• review
• approve
• create

Success criteria

• Manual validation confirms new starts the discovery phase
• generate submits backlog generation to the active AI CLI backend and persists generated_v1.yaml in the session directory
• review evaluates generated task content against release requirements and persists critique_1.json with a recorded score and verdict
• approve advances only a review-passing session to approval: Approved
• create submits work-item creation to the AI CLI and updates the same session to approval: Created while retaining the generated YAML artifact
• cargo test passes in the macOS validation environment

Assumptions

• The release is validated against the current local macOS developer workflow rather than a packaged installer flow.
• ScopeSmith session artifacts are stored under ~/.scopesmith/sessions/<session-id>/ and session.json is the source of truth for workflow_state and approval.
• The release validation uses a deterministic prepared session for generate, review, approve, and create so results can be reproduced during the same validation cycle.

Risks

• gh copilot or the active AI backend may fail because of authentication, tool availability, or prompt/response parsing issues.
• A command may print success while leaving session.json, generated_v1.yaml, or critique_1.json missing or inconsistent with the expected workflow state.
• Sequential command execution may expose gating regressions that are not visible when commands are exercised independently.

Initiative dependencies

• Local macOS environment with Rust toolchain, cargo, gh, and ScopeSmith build prerequisites available
• Authenticated and working gh copilot backend available for generate and create command execution
• Deterministic session fixture or repeatable manual input path that can produce a reviewable single-PBI backlog for validation
• Write access to ~/.scopesmith/sessions/ for session.json, generated_v1.yaml, and critique_1.json persistence checks

PBI fields

• id: PBI-001
• title: Validate the macOS release workflow and persistence contract for the latest ScopeSmith CLI
• goal: Prove that the latest ScopeSmith CLI release executes the required macOS workflow from new through create with correct gating, concrete persisted artifacts, and passing repository tests.
• rationale: Release readiness for ScopeSmith depends on the entire discovery-to-creation path working as one governed workflow, but completion evidence must be explicit at each handoff so acceptance is crisp and auditable.
• target_timeline: 1 release-validation cycle

Scope in

• Manual validation that new creates a session directory and writes session.json with workflow_state set to Discovery
• Validation that generate uses the active AI backend and writes ~/.scopesmith/sessions/<session-id>/generated_v1.yaml
• Validation that review writes ~/.scopesmith/sessions/<session-id>/critique_1.json and records a score and verdict in session history
• Validation that approve changes approval to Approved only when review output satisfies the release acceptance threshold
• Validation that create submits creation work to the AI backend, preserves generated_v1.yaml, and updates approval to Created
• Execution of cargo test on macOS as the release regression gate

Scope out

• Cross-platform validation outside macOS
• New feature development unrelated to release validation
• Replacing the current AI backend implementation or changing provider integrations
• Packaging, installer, or distribution-channel verification beyond local development execution

Acceptance criteria

• Running new creates ~/.scopesmith/sessions/<session-id>/session.json and that file records workflow_state: Discovery for the new session.
• Running generate against the prepared validation session invokes the active AI backend and writes ~/.scopesmith/sessions/<session-id>/generated_v1.yaml containing exactly 1 PBI.
• Running review after generate writes ~/.scopesmith/sessions/<session-id>/critique_1.json and records a critique score and verdict in session.json for the same session.
• Running approve is blocked unless the most recent critique meets the release acceptance threshold, and on success session.json records approval: Approved.
• Running create after approval invokes the active AI backend, keeps generated_v1.yaml present in the session directory, and updates session.json to approval: Created.
• cargo test completes successfully with exit code 0 in the macOS release-validation environment.

PBI dependencies

• Authenticated gh copilot access verified before generate and create are executed
• Prepared deterministic validation session available before generate is executed

Blockers

• None