Spec: Govern Project Settings and Scaffold State Safely

User Input

in @linear project https://linear.app/devpunks/project/harness-intelligence-23aceec78aca/issues we have new modules M7 M8 M9 for the refactor and re architecture around effect v4. so now please start a $delivery-phase FOR EACH SINGLE ONE of the EPICS. complete all epics and their inner stories with a delivery phase per epic

DO NOT MISS ON ANY OF THE STORIES

do this in full parallel. dont merge on main the subsequent pr

This specification covers Linear epic IP-318 and every child story beneath it: IP-327, IP-328, and IP-329.

Context

Project settings and managed scaffold state carry different kinds of authority, yet lifecycle commands must agree on the intended project state without overwriting operator choices or user changes. CLI operators and repository maintainers need command behavior that is deterministic, non-destructive, and truthful about every applied, skipped, degraded, conflicting, or failed action. Older settings must remain recoverable only when their meaning can be converted without guessing.

Non-Goals

• Giving commands independent settings-file read or write behavior.
• Reconstructing uncertain user choices during settings migration.
• Using the prior managed receipt as desired-state authority.
• Combining desired-state planning with repository observation, filesystem mutation, process execution, or conflict policy.
• Replacing whole structured configuration files when managed field-level changes are sufficient.
• Rolling back independent safe changes solely because another action conflicts or fails.

Acceptance Criteria

Project-setting authority (IP-327)

• User-selected provider and backlog choices, CLI-calculated required tools, and CLI-managed CLI or baseline versions each have one authoritative writer.
• Every lifecycle command obtains validated current settings through one shared component that reads, validates, and identifies safe upgrades while enforcing field ownership.
• Only commands that own the affected settings persist safe, unambiguous upgrades or other command-owned changes; hi check never persists settings changes.
• Older settings preserve user choices and upgrade only when conversion is safe and unambiguous.
• Ambiguous conversion produces a clear typed failure without guessing, discarding, or rewriting uncertain values.
• hi init owns initial adoption: it creates missing settings, captures provider and backlog choices, calculates required tools, and records the CLI and baseline versions used for the initial scaffold.
• hi scaffold retains the former scaffold-setup responsibility without gaining initial-adoption behavior.
• hi ensure changes only user provider and backlog choices and recalculates required tools; it neither reconciles scaffold state nor changes recorded CLI or baseline versions.
• hi check is read-only, including when settings require an upgrade.
• hi update preserves provider and backlog choices while recalculating required tools, updating managed version records, and reconciling managed scaffold state.

Deterministic desired state (IP-328)

• One desired-state contract serves hi init, hi check, and hi update.
• Its explicit semantic inputs are the neutral context plan, validated project settings, baseline or catalog information, and harness capabilities.
• Identical semantic inputs produce the same desired managed state for every consuming lifecycle command.
• Repository discovery, filesystem access, environment access, process execution, conflict policy, and application effects do not alter or enter desired-state derivation.
• Observation, comparison, and application remain distinct lifecycle stages: init applies, check compares, and update reconciles the shared desired state.

Non-destructive reconciliation (IP-329)

• The managed receipt records only successfully applied managed state and provenance and never defines desired state.
• Reconciliation compares desired state, observed repository state, and the prior receipt.
• Managed dependencies and structured configuration change at field or key granularity while unrelated user content remains intact.
• A user-modified managed file, dependency, field, or key that would be overwritten or removed is preserved and reported for explicit resolution.
• Independent safe actions proceed despite unrelated conflicts.
• Every action reports one typed outcome: success, skip, degradation, conflict, or failure.
• The receipt advances applied managed state only for successful actions; it records known omissions or degradations without claiming they were applied, while unresolved conflicts and failures remain unapplied so retries stay deterministic and truthful.

Constraints

• Desired state comes from explicit semantic inputs and never from the prior receipt.
• Observation, comparison, and application remain separate.
• Every operation preserves settings fields and repository content it does not own.
• Independent successes remain applied and reported even when another action cannot complete.
• IP-318 implementation stays on child branch team/stefan/ip-318-settings-state in one draft child PR based on team/stefan/refactor-cli-architecture, never main; keep it unmerged and undeployed.
• The blocker order governs task execution inside the IP-318 child PR. IP-327, IP-328, and IP-329 do not become separate PRs.

Branch/Base Intent

• Child branch: team/stefan/ip-318-settings-state
• Draft child PR base: team/stefan/refactor-cli-architecture
• Forbidden base: main
• Merge/deployment state: remain unmerged and undeployed
• Dependencies: IP-330: Classify and characterize every public behavior seam and IP-326: Project canonical contributions through explicit harness capabilities
• Evidence: Draft PR #76 and apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/IMPLEMENTATION-NOTES.md record completed, accepted IP-330 characterization evidence. IP-326 remains an external task-order gate before IP-328.
• Task order: IP-330 readiness is proven. IP-327 and IP-326 precede IP-328, which precedes IP-329. The IP-318 child stories remain tasks inside this epic PR, not separate PRs.

Decision Log

Review Status

• State: Approved
• Requirements authority: completed Q1-Q58 grill artifacts and Linear IP-318/IP-327/IP-328/IP-329, read in full on 2026-07-14
• Completeness check: parent outcome, constraints, relations, and every child-story acceptance signal and non-goal are represented
• Quality check: problem-space and binary-criteria self-review passed
• Independent review: complete; spec-reviewer found no blocking issue after settings persistence ownership and dependency readiness were corrected
• Human approval: complete; delivery is authorized to continue on the IP-318 draft child PR

Delivery Phase Handoff

• Phase: spec
• Status: complete
• Scope: IP-318 with IP-327, IP-328, and IP-329
• Artifacts: this SPEC.md
• Validation: frontmatter, story coverage, dependency ordering, and spec-quality self-check complete
• Review/debug/docs state: independently reviewed and human-approved; no implementation, runtime debugging, or docs ingest performed for IP-318
• UI Evidence: not applicable to this spec phase
• Next suggested route: create-plan on child branch team/stefan/ip-318-settings-state, targeting draft child PR base team/stefan/refactor-cli-architecture, while preserving IP-327 and IP-326 before IP-328, then IP-329
• Blockers: none at the spec gate