AI Assisted Version Intent

An opt-in analyze addon that reads a pull request diff and applies a semantic version intent by posting a /version comment authored by the app.

This feature is in limited preview — it is available to selected customers only, and behaviour and commands may change based on feedback. Reach out to the flxbl team if you would like early access.

AI Version Assist is part of Automated Package Versioning. It requires an sfp server with version management enabled, and an AI provider configured for the project.

Automated package versioning computes each artifact's version from the last published version and the intent of the change. Intent normally comes from a human — a conventional commit prefix, a version: footer, or a /version pull request comment. When none is given, the change falls through to a patch.

AI Version Assist adds a machine author for that intent. It runs as an addon inside sfp project:analyze, reads what the pull request diff actually does, and posts a single /version comment on the PR authored by the app. The build reads that comment through the same collector as a human /version comment — as a distinct, lower-priority tier. A human /version comment always overrides it.

How it works

The assist rides the existing pull request analysis flow — it does not introduce a separate trigger. On a PR event (opened, synchronize, reopened, ready-for-review), project:analyze runs its linters, and the version-assist addon runs last:

1. Maps the PR's changed files to packages, using the same mapping the version pipeline uses.
2. Keeps only the server-managed packages — those carrying 0.0.0.NEXT in sfdx-project.json.
3. Scores each impacted package from its own diff (major, minor, patch or none).
4. Posts — or edits — one sticky /version comment on the PR carrying the resulting directive and a rationale table.

PR opened / synchronize ─▶ project:analyze ─▶ version-assist addon
                                                    │
                        sticky /version comment ────┘
                                                    ▼
                     build reads it as the AI tier ─▶ source: ai
                     (a human /version always wins)

The assist is a participant in the existing primitive, not a new mechanism. Its output is a /version comment; the build's version pipeline is unchanged.

When it runs — three gates

All three conditions must hold, or the addon is silently skipped:

1. Version management is enabled for the project (versionManagement.enabled). This is the same project-level gate that automated package versioning uses.
2. The addon is enabled for the target branch (analyzeConfig.versionAssistEnabled). This defaults to off and is set per project, optionally per branch.
3. The PR impacts at least one server-managed package (a 0.0.0.NEXT package). A PR that only touches manually versioned packages is skipped.

The sticky comment

The assist maintains exactly one comment per pull request. Re-running the analysis after new commits edits that comment in place rather than posting a second one. The comment carries a /version directive line, a rationale table, and a hidden marker (<!-- sfp-version-assist -->) that identifies it as the assist's output.

/version core:minor sales-app:patch dependents:patch

### AI version assessment
| Package   | Suggested | Evidence                                    |
|-----------|-----------|---------------------------------------------|
| core      | minor     | adds AccountScoreService (new public class) |
| sales-app | patch     | internal refactor of OpportunityHandler     |

Override by posting a later /version comment — human comments always win.
<!-- sfp-version-assist -->

The /version line starts the comment so the build's collector reads the directive. Editing in place preserves the comment's original creation time on GitHub, so the assist never gains recency over a human comment.

How the intent is decided

The assist scores each impacted package from its diff — the removed and added lines, not the commit message or PR title. A removed public member is a breaking change even when the same PR also adds files. Each package gets exactly one intent:

Intent	Evidence required
major	A breaking change: a removed or renamed public/global Apex member, a removed or type-changed field, a removed permission/page/flow/API, or a new required parameter on a public method.
minor	A backward-compatible capability addition: new objects, fields, Apex classes or methods, flows, or LWCs that extend the package surface without breaking anything existing.
patch	A behaviour-preserving change: bug fixes, internal refactors, metadata tweaks. This is the default when the evidence is ambiguous.
none	Provably non-shippable content only: documentation, tests, or scratch-org config, with no deployable metadata change.

When a change alters an interface that other packages depend on, the assist may add dependents:patch to nudge the direct dependents — and only ever patch. Stronger dependents intents are mentioned in the rationale for a human to apply.

Precedence — humans always win

The build resolves each package's version intent in this order:

Priority	Source	Attributed as
1	Human /version PR comment	pr-comment
2	version: commit footer	explicit
3	AI Version Assist directive	ai
4	Conventional commit prefixes	conventional-commit
5	Patch default	default

The assist sits below every human-authored intent and above the derived defaults. A /version comment posted by a person for a package always overrides the assist's directive for that package, regardless of order. Comments carrying the assist marker form a separate, lower tier that a human comment cannot be outranked by.

When an AI-decided version is published, the baseline record stores lastVersionIntentSource: 'ai', so release audits show which bumps were machine-decided. The Computed Versions table printed during the build shows ai in its Source column.

For the full intent model that the assist feeds into, see Expressing version intent.

On cascade pull requests

A cascade opens an ordinary pull request, so the assist runs on it like any other PR. It reads the whole cascaded diff and suggests a bump for the packages it touches — it does not distinguish a cascade from original work. That suggestion cannot produce a spurious version:

• If the cascaded content is already published on the source line, the receiving build skips the package — no version is computed for it — so the directive is never applied.
• If the package does build, because the receiving branch has its own change to it, the version floor recognises the cascaded intent as already spent and does not re-apply it. The package takes its own intent for its own change.

In both cases the assist's directive on the cascade PR is inert. See Versioning across branches for the floor and skip behaviour.

Configuration

The addon is configured on the project, under analyzeConfig. It is off by default and can be turned on per target branch using the same first-match-wins branch rules as the other analyze settings:

"configuration": {
  "versionManagement": { "enabled": true },   // required — the project-level gate
  "analyzeConfig": {
    "versionAssistEnabled": false,             // addon default: off
    "branchRules": [
      { "pattern": "main", "versionAssistEnabled": true }
    ]
  }
}

versionAssistEnabled is a project (server) setting resolved from analyzeConfig, not a field in the local config/analyze.yaml. The server keeps the per-branch resolution in one place.

The AI provider resolves exactly as it does for the architecture linter: the project's aiProvider setting, then the project's AI integration credentials, then the default AI integration. Setting aiProvider: 'none' opts the project out. See Configuring LLM Providers for provider setup.

Running it manually

The same analysis is available as a standalone command, useful for testing on a branch before enabling the addon:

sfp project version suggest \
  --repository flxbl-io/sf-core \
  --pr-number 42 \
  --base-ref origin/main

This prints the suggested directive and the per-package rationale without changing anything. Add --apply to post or edit the sticky comment on the PR:

sfp project version suggest \
  --repository flxbl-io/sf-core \
  --pr-number 42 \
  --base-ref origin/main \
  --apply

Flag	Description
--repository	Repository identifier (required).
--pr-number	Pull request number. Required to --apply the sticky comment.
--base-ref	Base commit or branch for the diff (for example origin/main).
--head-ref	Head commit or branch for the diff. Defaults to HEAD.
--changed-files	Comma-separated list of changed files, overriding the git diff.
--provider	AI provider override (for example anthropic). Defaults to the project's integration.
--apply	Post or edit the sticky /version comment on the PR. Off by default.
--json	Emit the result as JSON instead of a table.

Failure posture

The addon is advisory only. A missing provider, exhausted quota, timeout, or model error causes the analyzer to report the version-assist check as skipped and post no directive. It never fails the analysis check and never blocks a build.

Where the results appear

The assist delivers its result through three channels:

• The sticky /version comment on the pull request — the directive the build reads.
• An informational check run (sfp Project Analysis - version-assist), alongside the other analyze checks.
• The analysis record surfaced in the codev Change Analysis area, where the assessment appears as its own tab.

Provider support

GitHub is supported first. Azure DevOps support is planned for a later phase — comment timestamps, which the sticky-comment behaviour relies on, are not always available there.