Provide first-class upgrade contract for installed projects

[dreamorosi]

The problem

Every ## [N.N.N] entry in the CHANGELOG ends with the same instruction: "Upgrade: re-copy your dist// shell into the project."

I work with enterprise customers rolling AI-DLC out across dozens of teams, and customers have already explicitly complained about the absence of a version-upgrade contract, and it is currently the top adoption risk they name, ahead of any missing feature.

One platform team evaluating v2 put it as a question the project currently has no documented answer to: "when a new version ships, what exactly do we need to copy, and what happens to the files we've modified?"

Why it bites at enterprise scale:

• It multiplies: N teams × M projects × (up to) 5 harnesses, on a cadence that recently exceeded ten releases per week. Nobody re-copies by hand at that rate; teams fall behind and the fleet fragments across framework versions, which then undermines the shared-methodology value proposition that brought these customers here in the first place.
• It's lossy: a blind cp -r can clobber files users have legitimately modified (agent model pins, settings, org rules seeded into the shell). There is no documented boundary between framework-owned and user-owned files in an installed project.
• It's silently breaking: some releases change contracts for scripts and integrations (e.g. 2.5.0: direct aidlc-state.ts lifecycle mutations now fail with an engine-ownership error). Without an upgrade step that surfaces this, adopters discover it mid-workflow or worse, lose any time savings that the framework purports to materialize.
• GA raises the bar: the README now declares the install model stable and advises pinning a known-good version — but there is no supported mechanism to move from one pinned version to the next.

What enterprise adopters need

1. A documented upgrade contract: which paths in an installed project are framework-owned (safe to replace), which are user-owned (never touched), and which are merge-required.
2. An upgrade command — PR feat(tools): add upgrade subcommand for in-place AI-DLC install upgrades #535 already implements exactly this shape (aidlc-utility upgrade with --dry-run, harness auto-detection, user-file preservation, cross-major refusal). It has been open since early July; no maintainer feedback; please prioritize shepherding it (or an equivalent) into core.
3. A per-release compatibility statement in the CHANGELOG: "config-compatible / script-breaking / re-compose required" — one line that lets a platform team triage whether an upgrade is a copy or a migration.

[leandrodamascena]

Hi everyone, I was reviewing this issue and it looks like most of its scope now overlaps with #722. The ownership model, safe project updates, version skew detection, file preservation, and upgrade behavior are all being discussed there as part of the broader installation and distribution design.

Keeping both issues active may create two places for the same decisions and implementation updates. Would it make sense to consolidate this work under #722 and close this issue as covered by that RFC?

If #722 provides update and configuration tools that detect and safely apply required changes, much of this problem may be handled automatically. A dry-run could show what will change, while doctor could identify version skew or required migrations before a workflow starts.

Still, I understand the value of clearly stating the compatibility impact of each release. Platform teams managing many projects need to know whether an update is transparent, requires project configuration, or includes a migration. Semantic versioning should already provide this signal, although I recognize that we have not always applied the patch/minor distinction consistently.

This information could be included in the release notes and release metadata, while the tooling enforces the actual upgrade contract. That would preserve the main requirement from this issue without creating a separate implementation path.

[harmjeff]

+1 — additional field data from AI-DLC v2 testing corroborates this:

• Bug, severity High, phase General / Cross-cutting: AIDLC v2.8.0 on Windows: (1) PowerShell file manipulation broken (worked in previous versions); (2) High token consumption and longer-running stages vs V1; (3) Customer frustrated with upgrade experience, wants downgrade path to 2.7.x.
• Bug, severity High, phase General / Cross-cutting: Upgrade from within 2.x version are not smooth. The intents needs to be archived and renabled. Almost close to remove the inlfight intents and restart the workflow.
• Documentation, severity Medium, phase General / Cross-cutting: Customers do not know how to upgrade or downgrade AIDLC versions. This mattered at this workshop because the mitigation for the hook failures was a downgrade, which the teams could not perform themselves.

[github-actions]

I reviewed issue #636 and its current conversation as a proposed product and workflow change.

Final Assessment

Human decision aid only: Readiness 5/5 is best; Risk 1/5 is best. These scores do not prioritize, approve, reject, or implement the issue.

Readiness: 2/5 — The enterprise need is clear, but the requested mechanism predates the shipped native lifecycle. The remaining deliverables and channel guarantees need redefinition before planning.

Risk: 4/5 — An ambiguous upgrade contract can cause fleet version fragmentation, project-file conflicts, and unsafe assumptions about active workflows or downgrade recovery.

Findings: 1 blocking question, 2 recommendations.

Validation performed:

• Bug verification: classification not-bug; status not-run; no tests were selected or run.

Category Assessment

Intent and Problem Clarity

No material gap identified.

Direction

No material gap identified.

User Experience

1 finding; highest priority: P2.

Scope and Outcomes

2 findings; highest priority: P1.

Feasibility and Dependencies

No material gap identified.

Risks and Open Decisions

No material gap identified.

Findings by Priority

P1

Scope and Outcomes · Blocking question: Re-scope the proposal against the shipped lifecycle

Evidence: issue body: “An upgrade command — PR #535 already implements exactly this shape (aidlc-utility upgrade with --dry-run, harness auto-detection, user-file preservation, cross-major refusal).”, docs/guide/18-install-and-lifecycle.md: “`aidlc config` is local-only and transactional. It creates the selected harness
tree, the `aidlc/` workspace shell, root integrations, a projection stamp, and
an ownership baseline. It does not create a workflow intent.”, CHANGELOG.md: “**Upgrade:** run `aidlc update`, then run `aidlc config --yes` in each project to refresh its harness runtime.”, CHANGELOG.md: “Manual-copy users must replace the complete `runtime/<harness>/` tree from `aidlc-copy-runtime-2.9.0.tar.gz`.”, issue #1047: “Release process change: native distribution and project configuration from v2.8.0”.

Concern: The issue still requests the superseded utility-command design even though native machine updates, transactional project refresh, and ownership baselines now exist. It does not identify whether the residual work is documentation, release metadata, safer copy-channel refresh, additional migration behavior, or work already owned by issue #1047.

Why it matters: Planning could duplicate shipped functionality or leave manual-copy adopters without the preservation guarantee the issue intends to establish.

Suggested issue change: Replace the requested command implementation with a current-state matrix covering native machine update, native project refresh, and every supported copy-channel harness. Mark what is already shipped, identify each residual deliverable and acceptance criterion, and state the relationship to #1047.

P2

User Experience · Recommendation: State the active-workflow and downgrade boundaries

Evidence: comment by @harmjeff: “Upgrade from within 2.x version are not smooth. The intents needs to be archived and renabled. Almost close to remove the inlfight intents and restart the workflow.”, comment by @harmjeff: “Customers do not know how to upgrade or downgrade AIDLC versions.”, docs/guide/18-install-and-lifecycle.md: “A refresh changes project engine and graph files, so config refuses while any
workflow in any space is not complete. Parked workflows still count as
active. Complete every workflow named in the error, then rerun config.”, docs/guide/18-install-and-lifecycle.md: “`aidlc update` and `aidlc use` remain safe during a workflow because
they only change machine state.”, docs/guide/18-install-and-lifecycle.md: “There is no public rollback or retained-version management command.”.

Concern: The field evidence expands the user need to in-flight upgrades and downgrades, while the current lifecycle distinguishes safe machine updates from blocked project refreshes and offers version selection without a public rollback command.

Why it matters: Fleet operators may infer that project refreshes or downgrades are supported in states where the current contract refuses them or cannot restore project compatibility.

Suggested issue change: Add an explicit support table for running, parked, archived, and completed workflows, separating machine update from project refresh. State the supported downgrade procedure and limits, or split in-flight migration and rollback into separately scoped follow-up work.

Scope and Outcomes · Recommendation: Define a testable compatibility-statement schema

Evidence: issue body: “A per-release compatibility statement in the CHANGELOG: "config-compatible / script-breaking / re-compose required" — one line that lets a platform team triage whether an upgrade is a copy or a migration.”, AGENTS.md: “Each release entry follows the shape: `## [N.N.N] - YYYY-MM-DD` heading, one-paragraph summary that includes any upgrade instruction, then a flat bullet list focused on what users actually invoke (commands, flags, errors they see, breaking changes for CI/scripts).”, CHANGELOG.md: “Engine replacement restores the stock graph, so `/aidlc plugin sync` is required after every upgrade; automation must treat exit 1 as an incomplete plugin installation when configured roots are unusable.”.

Concern: The three proposed values are not defined as exclusive or combinable and do not specify how project refresh, plugins, scripts, trust changes, or state compatibility are represented or enforced.

Why it matters: Release authors and platform teams could interpret the same compatibility label differently, weakening the promised fleet-triage contract.

Suggested issue change: Define fixed fields and allowed values for project refresh, plugin action, script compatibility, trust re-approval, and state migration. Specify whether the contract is changelog-only or also machine-readable, and add acceptance criteria requiring every release entry to supply it.

Residual risk: Even after clarification, compatibility guarantees will remain bounded by historical releases, locally modified framework files, copy installs without a usable ownership baseline, and state-schema changes that older builds cannot read.

Decision

Alignment: Aligned — A first-class installation lifecycle and compatibility contract supports AI-DLC's intent-led, multi-harness software-factory direction.

Highest priority: P1

Next decision: Author — clarify the issue before planning. Recast the issue around the gaps that remain after the current update, config, ownership, and version-selection features, and explicitly define native versus copy-channel coverage. That scope decision is needed before maintainers can plan the work.

Reviewed by AIDA (AI-DLC Developer Agent).