AI-DLC Release Compatibility
This document describes how AI-DLC catalogs are imported, evaluated, selected, and resolved at runtime. A release can only be promoted when every behavior it authors has a runtime handler in this build; the admin tab lists any missing handlers.
Release contract
An AI-DLC release is identified by its source commit and importer revision. Its catalog, source objects, compatibility report, and closure digest are stored as immutable objects. The registry may add operator state such as visibility, support state, notes, and channel membership, but it cannot change the bytes an intent already pinned.
Release compatibility is based on the imported content and runtime handlers, not version-string comparisons. A release can be importable and structurally valid without being selectable. Importing a profile never publishes it to users or changes an existing intent.
Profile identity and trust
The built-in profiles are pinned to exact upstream commit SHAs. The allowlist includes the current 2.3.3 baseline and the 2.6.18, 2.7.0, 2.8.2, 2.9.0, and 2.11.0 and 2.11.1 catalogs. No intermediate release is onboarded: 2.10.0 is not on the allowlist and registering it is refused as an unknown profile. A custom fork receives a synthesized profile with its own source identity; an unknown tag or branch is not treated as an official release.
All official profiles use the same source trust tier. Trust establishes whether the imported source may run; it does not certify that the platform reproduces every semantic in that source.
A custom fork names the official profile whose frontmatter dialect it uses (for
example v2.9.0); that base grants no trust. It is recorded T0 and
import-only, and it may author its own stages, scopes, agents and sensors. It
becomes runnable only through the explicit admin promotion described under
Registry, promotion, and channels, which
applies the same fidelity guard as an official release.
Fork sources
A fork is read from one of two places, always at an exact 40-hex commit SHA:
- GitHub, written
owner/name. It is fetched from codeload without credentials, so the repository must be public. - GitLab, written
gitlab:<namespace>/<project>, for examplegitlab:acme/platform/aidlc-fork. Nested groups are allowed. It is fetched through the project archive API of the instance inaidlc_custom_source_gitlab_url(defaulthttps://gitlab.com). For a private project, store a token with theread_apiscope in a Secrets Manager secret, either as its plain value or as thetokenfield of a JSON object (the shape a rotation function keeps alongside the token's id), and setaidlc_custom_source_gitlab_token_secret_arnto its ARN. A project or group access token with at least the Reporter role works. Only the seed-blocks function may read the secret, and the token is sent only to that instance, in theAuthorizationheader. GitLab rate-limits archive downloads per project and commit, so a repeated import of the same commit can briefly answer 429.
The repository string is the fork's identity: it is part of the release id
(aidlc-custom:gitlab:acme/platform/aidlc-fork@<sha>) and of its storage prefix
(custom/gitlab/<url-encoded project path>/), so a GitLab fork can never share
bytes with a GitHub fork or an official release. Either way, only the core/
tree is imported.
Immutable storage and import
The seed-blocks import mode fetches the profile's declared source closure, normalizes known frontmatter dialects, maps blocks, and writes a content-addressed release bundle to S3. The manifest records the source SHA, importer revision, catalog digest, object digests, and compatibility evidence. Conditional writes prevent an import from replacing existing bytes.
The importer revision includes a fingerprint of the block mapper. Mapper keys and frontmatter normalization are defined for the supported profile set. A mapping change alters the importer fingerprint and catalog goldens, so it requires a new importer revision and closure upgrade. Runtime handlers may be added for fields already recorded in a catalog without changing that catalog.
The 2.3.3 block digest and per-scope plan digests are compatibility contracts. Optional mapper and plan properties are omitted when the source did not author them, preserving byte identity for existing 2.3.3 runs.
Release-aware resolution
When release pinning is enabled, an intent stores its release ID and closure digest at creation. The runtime verifies the manifest and each object before loading the pinned catalog. A pinned run therefore resolves from its own immutable closure rather than from mutable system blocks or the newest upstream catalog.
Standard deployments enable release selection by default after preparing the
supported catalogs. An explicit aidlc_release_pinning = "off" (or the demo
environment's AIDLC_RELEASE_PINNING=off) remains an opt-out. When off, new
intents follow the existing platform-default path and do not receive an
implicit release pin. The new-intent page only displays a version selector when
the API confirms that pinning is enabled. If the flag changes while the page is
open, a rejected pin is retried as an unpinned intent and the UI reports the
fallback.
When pinning is enabled but no stable channel is configured, intent creation may
still pin the deployment ref's release. The registry is consulted first: the
closure is pinned only if the matching registry record is registered, visible,
selectable or certified, and its authored behavior passes the runtime promotion
guard. If there is no such record, or it is not eligible, or it authors behavior
this build cannot honour, the intent is created on the existing unpinned path
without reading the manifest. The manifest is read only once a record exists,
because the runtime role has no s3:ListBucket and S3 answers a read of a
never-imported ref with 403 rather than 404.
The deployment ref's manifest is addressed by the running build's importer
revision. After an importer revision bump, an eligible record still describes
the previous revision until the release is re-imported and the record upgraded,
and a record whose closure does not match the published manifest is in the same
half-finished state. Both keep the intent unpinned with a
release_registry_skew warning instead of failing the create; the revision
check uses the record alone, so the missing new-revision manifest is never
read. An explicitly selected or stable-channel release is pinned by the
record's own importer revision and is not affected.
A configured stable channel is an implicit default and degrades the same way. If a space has a user block edit the stable release cannot overlay, and the release itself resolves cleanly without that overlay, the create continues as if no channel were set instead of failing: it auto-pins the deployment ref's release when that release can apply the overlay, and otherwise creates the intent unpinned. An explicitly requested release is strict: it returns the resolver errors so the caller sees which override conflicts.
A failure to complete that lookup is treated differently. A throttled registry
read, or a denied, missing or corrupt manifest or closure behind an eligible
registry record, means the answer
is unknown rather than "not published", so intent creation returns
503 release_resolution_failed and writes nothing. Downgrading an unreadable
manifest to "does not exist" would let a permissions regression silently unpin
every new intent.
Existing intents are not migrated or repinned. Release-aware compose reads use the intent's stored pin, so reopening an intent does not silently change its methodology version.
Compatibility evidence and runtime support
The analyzer reports structural validity, dependency closure, sensor command
compatibility, mapped frontmatter values, and runtime-command fidelity. The
dependency closure follows a sensor script's relative imports the way Bun
resolves them, including a TypeScript-style ./lib.js specifier for a published
lib.ts. Each
authored value is classified as native, approximated, unsupported, or
packaging-only. The report includes the specific source values that the
current runtime does not honour.
The runtime supports the single-session stage mode, and the per-persona session
mode for pinned pipeline, mob, and subagent-with-supports stages whose
release closure ships core/aidlc-common/protocols/stage-protocol-ensemble.md.
It also supports the platform's always-restored workspace behavior. The mapper and analyzer know the complete
frontmatter vocabulary of all five profiles, but knowing a field is not the
same as executing its semantics. Other authored values remain unsupported
until the corresponding runtime handler is registered and implemented. This
distinction keeps newer imports inspectable without presenting them as
safe-to-run releases.
The gate handlers cover summary and plan-approval checkpoints, review policy,
both sensor planes, change control, learnings, skeleton selection,
AGENT.maxTurns, and the build-and-test loop-back. The persona runtime
dispatches pipeline and mob stages, and subagent stages that declare
supports, in separate serial sessions with role-scoped briefs. A subagent
stage gets separate sessions only when its release closure ships
core/aidlc-common/protocols/stage-protocol-ensemble.md; without that file a
subagent stage with a support stays a single delegated session, which is why
2.3.3 reverse-engineering is unchanged. agent-team remains unsupported
because it requires concurrent sessions.
The 2.3.3 baseline remains promotable. The 2.6.18, 2.7.0, 2.8.2, and 2.9.0
fixtures have runtime handlers for their authored persona modes and for the
build-and-test loop-back, so PROTOCOL:build-and-test-loopback is no longer
unsupported — the gap that made the release-promotion guard refuse them. Their
compatibility classification remains field-driven and reflects the supported
runtime semantics rather than profile-version exceptions.
Those fixtures carry no bodies, so they do not show one more condition. From
2.8.2 on, a release's prompts invoke the upstream engine CLI as
{{INVOKE}} engine <command>, and the guard reads those invocations out of the
published closure as BODY:{{INVOKE}} gaps. It reads them only from what
reaches a prompt: the bodies of the blocks a release library resolves (stages,
agents, sensors, rules, artifacts, knowledge, scopes) and the conductor. The
engine's own sources, hooks and protocols, and the SKILL and TEMPLATE bodies,
ship in the closure and quote engine commands too, but no prompt renders them,
so they are not read as gaps. The 2.6.18 and 2.7.0 prompts invoke no engine
command.
No engine binary exists here. The stage, persona and compose prompts neutralize
the token and append the engine-command annex, a closed list that tells the
agent, per command, what to do instead. A prompt carries the annex when a part
the release authors to INSTRUCT the agent carries the token: the stage body, the
conductor, the persona or the reference knowledge in a stage prompt; the persona
or the reference knowledge in a reviewer or ensemble brief; the composer persona
or its knowledge in the compose prompt. lambda/shared/annex-reach.js is the one
definition those builders and the promotion guard share. A command the annex
answers does not hold promotion when EVERY block whose body carries it is one of
those: bodies are content-addressed, so one object can be the body of several
blocks, and coverage for a stage is not coverage for a rule that shares the same
text.
| Command | Handling | What the platform does |
|---|---|---|
orchestrate report |
unsupported, answered | Records stage lifecycle itself from the turn ending. |
recompose --add, state set-construction-iteration, state practices-event, state practices-promote |
unsupported, answered | The agent records a recommendation for the human instead of performing the action. |
graph ars |
unsupported, answered | No composite is computed or shown. Upstream's score is advisory and nothing routes on it; the agent justifies each EXECUTE/SKIP with evidence and never presents a score. |
gen scope-table, gen stage-table |
approximated, answered | Read-only reporting the prompt already carries. |
workspace detect, workspace codekb, workspace codekb-scope-diff |
approximated, answered | Read-only reporting. The compose prompt carries the workspace signals the platform detected; a stage reads the compiled context and its working tree. No scope-diff identifier is minted. |
worktree, worktree create, worktree merge, worktree info |
approximated, answered | A per-unit lane runs on a unit branch the platform creates from the intent branch and checks out before the stage; any other stage runs on the intent branch. The platform merges each unit branch into the intent branch with --no-ff after the unit, and the intent branch reaches main through its pull request. |
graph validate-grid |
approximated, answered | The plan resolver re-validates every compose proposal (strictly when in flight). Not reproduced: the validator summary, nearest_stock, the keyword collision check. |
Any other command, including other subcommands or flags of these families and a
family name on its own (state, orchestrate --next), gets only the annex's
catch-all (say it is unavailable, never improvise), which leaves the
authored step unperformed, so it still holds promotion. So does an answered
command — including an approximated one, whose platform substitute the agent
only learns from the annex — found in a body whose prompt carries no annex, such
as a rule or a scope. One such consumer is enough: the verdict is the same
whether that body is shared with a stage or authored separately. With these,
2.8.2 and 2.9.0 author nothing this build cannot honour and are promotable. The admin tab lists
exactly what a given import still holds on. A gap list stored by a build that
read other files is re-read from the closure the next time it is listed or
promoted.
readyForCertification is derived from the current compatibility report. It is
not a version allowlist, and the report's Boolean is not treated as durable
authorization by itself: the release-promotion guard stores the authored
fidelity gaps and reevaluates them against the handlers in the running build.
2.11.0 promotes exactly as 2.8.2 and 2.9.0 do: an admin may make it
selectable, and certified — and so eligible for the stable channel — if
they decide to. The engine commands below are answered, not reproduced, which is
the same situation 2.8.2 and 2.9.0 are already in; whether that is a claim worth
making is the administrator's call, taken with the table below in hand.
AI-DLC 2.11.0: handled, approximated, refused
2.11.0 renames Change Control to Guard Policy (adding a third value, off)
and adds Plan Approval, collaborators and existing_code as scope
settings. All four are mapped by the importer, resolved onto the per-stage
policy, and choosable per intent by a space member before the run starts.
Guard Policy off means no change-control reopen; it never removes a human
approval gate, and that invariant is asserted for every 2.11 scope and stage.
| 2.11 behaviour | Disposition | What the platform does |
|---|---|---|
Guard Policy strict / relaxed |
approximated | The existing change-control gate, unchanged. |
Guard Policy off |
approximated | No reopen and no change-control prose. Upstream's off also lowers execution fences this platform never had, and its per-fence Guards Off/Guards On overrides and kill-switch chain are refused — there is no per-fence surface. |
Plan Approval on |
approximated | The existing outcome-gate approximation. |
Plan Approval off |
approximated | No plan gate is offered and the completion ladder requires no plan receipt. The stage's own approval gate is untouched, and the gate carries a notice naming whose choice it was. |
collaborators off |
native | One session: the lead agent produces every declared output. Each withdrawn persona is named on the plan's policy effects. |
collaborators on |
approximated | The existing per-persona blind sessions. |
existing_code |
approximated | Becomes the default project type, overridable by a human, and stated in the prompt. Mid-run reclassification is refused (see orchestrate next). |
sensors, learnings, summary_confirmation, review_cap |
as before | Already mapped; only their 2.11 defaults changed. review_cap stays a scope ceiling and raising it per intent is refused. |
| The composer's settings proposal | handled | guardPolicy, the six scopeSettings, baseScope and creationDepth are parsed and kept; a member accepts them on the compose page and the provenance is recorded. A proposed settingsChanges (a change to work in flight) is refused by name. |
engine audit append-raw |
approximated | The note is bound to emit_stage_note. No upstream audit shard or taxonomy event is written, and the agent may not claim one was. |
engine config get |
approximated | The effective settings and their source are rendered into the prompt. The annex forbids reading a settings, environment or shell file to find them. |
engine now |
approximated | The platform's own event stamps are in the prompt; a timestamp it cannot supply is omitted and said to be unavailable, never fabricated. |
engine config set |
refused | Settings belong to the intent and only a human changes them, before the run starts; afterwards the API answers settings_locked. The agent records the request. |
engine log answer, engine log decision |
refused (protected checkpoints) | Ordinary questions and summary confirmations bind to ask_question / confirm_summary where the session has them; where the policy or checkpoint ownership withholds one, the annex says so and defers to the stage's own session. The plan-approval receipt and the approved verification command have no store here and are named as unavailable. |
engine orchestrate next |
refused | No rescan, no Reverse Engineering re-insertion, no return to the interrupted stage. The agent records a RECOMMENDED PROJECT TYPE CHANGE and a human rewinds and recomposes. |
engine state set-construction-execution |
refused | Construction scheduling is platform state; the agent records the intended value. |
engine state set-construction-verification-command |
refused | No approved-command store; the command is a recommendation, never executable authority. |
engine testing-posture restore |
refused | No approved-bundle restore; the agent says it is unavailable and names what was lost. |
engine worktree list / discard / restore / purge |
refused | No parked-attempt store. Lanes are branches the platform creates and merges; the agent parks, deletes, restores and purges nothing and never substitutes git. |
testing-posture fingerprint --reapprove |
retired upstream | This platform never ran it, and no adapter here revives the retired route. |
doctor |
refused | No source-boundary diagnostic runs here. The agent reports the failure through its own output and never emits VALID/INVALID. |
workspace codekb-scope-diff --check |
refused | No publication validator runs here. The missing prerequisite is named; no verdict is produced. |
Every name the guard honours carries a row in the annex, asserted verbatim by test, and honouring a name requires proof that the answer REACHES the session that receives the command. Two reaches are distinguished, because the answers differ in what they need:
- A refusal that names a platform channel (record the request, put it in the findings) is honoured only where the session receiving the annex also owns that channel. A command instructed only from a reviewer's or a support persona's knowledge keeps holding promotion.
- An approximation whose answer the receiving session performs itself —
omit an unavailable timestamp, read the settings out of the prompt, record a
note — is honoured wherever a prompt carries the annex at all, which includes
that reviewer and support knowledge. A body no prompt builder annexes, such as
a persona, carries no answer for anyone:
engine nowmoved into a persona body holds promotion with the command named, which is how a fork is kept from inheriting a reach claim the official bodies earned.
The checkpoint mapping is rendered for the session that receives it: tool
registration withholds confirm_summary where the policy asks for no summary
confirmation and withholds both checkpoint tools from a session that owns no
checkpoint, so the annex offers only what that session has and otherwise says
the checkpoint cannot be raised there and must be deferred to the stage's own
session.
AI-DLC 2.11.1
2.11.1 is a patch release on the 2.11 line. It has the same frontmatter dialect, scope settings and sensors as 2.11.0, promotes the same way, and invokes every 2.11.0 command in the table above. It adds one:
| 2.11.1 behaviour | Disposition | What the platform does |
|---|---|---|
engine sensor-<id> --stage (build-and-test's cross-unit coverage gate, Step 10) |
refused | The platform runs a stage's declared sensors itself, at the stage's gate, and offers no way to run one on request. The agent writes the coverage report the step asks for from the record it can read, says it is agent-derived rather than sensor-verified, and treats every element it cannot confirm as uncovered, so it is surfaced at the gate. |
The bare engine sensor-<id> a sensor block declares as its command is a
different case, unchanged: the platform's sensor plane runs it at the gate.
2.11.0's sensors, and 2.11.1's, run as the release declares them, with one bounded difference:
- Document-sensor routing and script closures. 2.11 authors its document sensors against an output path and splits their scripts across sibling modules. The runner spawns each script on the flag its input schema declares and writes the script's pinned import closure beside it before spawning, so the traceability, type-check, claim-sources and linter sensors analyse their input instead of failing at import. A closure or import the release store cannot read is a release-integrity failure: no script is launched and the stage is held.
- Code-sensor budgets. 2.11 authors 1,200 seconds for the code sensors. The runner honours an authored budget up to its 600-second ceiling and within the stage deadline, and records which of the two bounded the run, so a sensor cut at the ceiling is reported as such. This is the remaining difference: a code sensor that needs more than 600 seconds is cut shorter than the release asks.
- The timestamp-heading exemption. 2.11 widens its record sensors to the knowledge base and exempts a one-line timestamp record from the heading floor, and the runner honours that exemption for a catalog that authors it. Earlier releases do not, so such a record still reports two missing headings there.
AI-DLC 2.11.3
2.11.3 imports from the pinned commit
63fd2901947ece8c5ad0cd831cdf5934a9666d47, the preview commit the v2.11.3
tag was promoted from; the promotion commit changes only release metadata. It
keeps the 2.11 frontmatter dialect, scope settings, sensor declarations and the
eleven compilable scope plans.
Its Requirements Analysis outputs description has an unquoted colon that
makes the upstream YAML invalid; importer revision 4 quotes that known scalar
without changing its value. Its sensor scripts import sibling modules by their
emitted .js name; importer revision 5 resolves those to the published .ts
files, so its recorded dependency closure is complete.
The 2.11.3 adapter keeps repository membership fixed and supports an optional human plan review. Administrators can inspect these differences before approval:
| 2.11.3 behaviour | Disposition | What the platform does |
|---|---|---|
engine intent add-repo |
refused | Repository membership and credentials are fixed on the intent snapshot. Ask a human to add the repository to the project and start a new intent. |
engine intent add-checkout |
refused | The agent cannot add an arbitrary local checkout to the reviewed source manifest. Only repositories already bound to the intent are in scope. |
engine plan first |
adapted | Use request_plan_approval when available, otherwise a recorded ask_question containing the plan and test instructions. The lead waits for the answer. This does not change the configured policy or reproduce the native one-off flag. |
Two sensor behaviours change upstream in 2.11.3 and are not reproduced:
engine sensor-traceability --stage <stage> --output-path <path> --write-upstream. Eight stages run it to write the stage's required upstream ids and an initialGAProw for each into its traceability record. It is handled like any sensor run on request: refused. The agent writes the record itself from the artifacts it can read, labels it agent-derived rather than sensor-verified, and records every id it cannot confirm as uncovered, so it surfaces at the gate. The record is not initialized by the upstream tool.- Dispatcher outcomes. Upstream's sensor dispatcher now reports a script
error or unreadable output as
could-not-runrather than a noted pass, and can dispatch over a set of paths. The platform runs a stage's declared sensors through its own runner, one matching file at a time, and maps their exit codes itself, so these dispatcher outcomes do not apply.
The 2.11.3 release is structurally valid and can be promoted after these limitations are reviewed. A workflow that requires any of the refused operations is not supported by this runtime.
What these green tests do not prove, stated so the support claim stays bounded: real model behaviour under the truncated composer knowledge; live human reply, approval, edit and restore flows; reviewer and support prompts in a real run; a real ESLint or tsc subprocess in the container image; per-Unit checkpoints and reopen with finished work retained; and production-equivalent dependency packaging.
Registry, promotion, and channels
Registration creates an invisible, structurally-valid record. It does not make the release selectable. An administrator explicitly changes the support state and visibility, and channel pointers refer only to eligible records.
Before a release becomes selectable or certified, the registry verifies the
immutable catalog and source objects, derives authored fidelity gaps, and
checks those values against the runtime capability registry. If any authored
value is still unsupported, the update fails with
release_capability_unhandled and returns the unhonoured values. The stable
channel retains its current-platform-baseline exception so the existing 2.3.3
baseline remains available. Other channel updates are subject to the same
runtime-relative guard.
The same guard applies when visibility is enabled for an already-selectable release and when its closure is upgraded. Before trusting cached or legacy evidence, the registry verifies the published manifest identity against the registry row and re-reads bounded, digest-checked catalog objects. An upgrade that adds behavior the running build cannot honor is refused before new intents can select it.
A custom fork is promoted the same way. Registration records it T0,
import-only and invisible, with its fidelity gaps and the unhonoured subset on
the record. Promoting it to selectable or certified runs the guard above
over the fork's own closure: if every behavior it authors has a runtime handler,
the record becomes runnable and can then be made visible, pointed at by a
channel, and pinned by new intents; otherwise the promotion is refused with
release_capability_unhandled and the record stays import-only. Nothing else
makes a fork runnable, and a fork registered by an earlier build is in the same
state until it is promoted. A fork's intents pin a closure that names the fork,
and the runtime reads that closure only from the fork's own storage prefix; a
custom closure is never executed under an official pin. The runtime also reads
the fork's release record before it loads the closure and refuses the pin with
release_not_runnable unless the record is runnable, so a fork pin written by
hand or restored from a backup does not run a fork that was never promoted.
Promoting a fork is a trust decision. Earlier builds kept every fork
import-only until sandboxed execution and IAM isolation existed; this build lets
an admin promote one, and neither of those exists yet. A promoted fork's sensor
scripts, and the command each sensor declares (a runtime: sh command runs
through sh -c), run in the agent runtime with the runtime's own role and no
separate sandbox. That is how a user's script sensor runs too, but the blast
radius is wider: a user's sensor runs only in that user's intents, while a
promoted fork is offered to every space in the deployment. Only a platform
admin can promote a fork, the guard refuses a fork that authors behavior this
build has no handler for, and promotion is not revoked once granted. Promote
only a fork whose sources you would run as your own sensors in every space.
Because the registry reevaluates content evidence against the current handler registry, adding a handler can make an existing import promotable without changing its source bytes, importer revision, or closure digest. The registry API exposes both the original fidelity gaps and the subset this build still cannot honour; the admin screen explains a refused promotion.
Admin version workflow
The admin page shows Stable and Preview assignments immediately, with a compact table of five versions per page. Search covers every version, status and source repository, including versions on other pages. Stable is the default for new intents. Version links open the upstream GitHub release (or the pinned source for commit-only profiles). Dates are upstream GitHub publication dates; import and commit dates are never substituted. Select a version to expand its actions directly beneath the row. Only one row expands at a time, and the list stays usable. Compatibility and contents explains limitations and opens the pinned workflow and blocks. Maintenance contains visibility, retirement, import repair and admin notes. The entire version row opens its controls; an optional source link opens separately. Named versions without a source URL remain usable without a link.
- Test version is optional. Compatibility is checked automatically if needed, keeping an unapproved version unlisted, then the admin chooses a v2 space for a normal workflow intent pinned to that exact release. The draft and results follow the space's sharing permissions and use its runtime/model budget. Platform-admin access is required to create and start a validation intent.
- Approve for use checks compatibility and makes the version available to users. Approval is an administrator's rollout decision, not a claim that an automatic test ran. There is no completed-run prerequisite.
- Make stable selects the default for new intents. Use as preview assigns the preview channel. Existing intents keep their original version.
- Maintenance → Replace stable with switches the default to another eligible version, including an older approved release. Preview and Candidate labels can also be removed here.
- Deprecate version removes it from new-intent choices while existing intents continue. Replace or remove channel assignments first. Approval can make a deprecated version available again; raw import/support states remain under Import details and advanced state.
Validation intents persist an informational methodologyReleaseTest marker.
Only an authenticated platform admin may request this mode, with an explicit
release and release pinning enabled. It relaxes visibility at selection only:
unqualified, non-runnable and existing-only releases are still refused, all
closure and plan checks still run, and no runtime execution check is bypassed.
Enable pinning and promote a release
The standard installer and deployment scripts publish and register all eight
supported official versions, including 2.11.3. Preparation is idempotent, runs
after the baseline reseed (or after it is skipped with --skip-seed), and fails
deployment if a catalog cannot be prepared; the error names the command to retry
it. It preserves existing approvals, visibility, notes and channel choices, and
does not approve new versions.
When a deployment raises the importer revision, preparation moves each registered official version to the closure it just published, through the same checked upgrade an administrator runs. Intents already pinned keep the closure they started with; only new intents pin the new one. If the registry refuses an upgrade, for example because a channel would no longer be satisfied, the version stays on its older closure, the deployment prints a warning, and the releases tab shows Upgrade needed in its status.
After deployment:
- Deploy normally. Version selection is enabled by default. If the deployment
explicitly opted out, remove that override or set
aidlc_release_pinning = "on"; the demo workflow also acceptsAIDLC_RELEASE_PINNING=on. Preparation never changes an existing Stable choice. If none is selected, the configured platform baseline continues to serve new intents. - In the admin AI-DLC releases tab, select the version and choose Approve for use. Compatibility is checked automatically. Test version is optional.
- Choose Make stable for the default, or Use as preview for an opt-in channel. Existing intents keep their original version.
For direct Terraform applies, run the same preparation step from the repository root after deploying the seed Lambda:
AWS_REGION="<deployed region>" \
SEED_BLOCKS_FUNCTION="<seed_blocks_lambda_name output>" \
node scripts/prepare-aidlc-releases.mjs
Custom forks still use the explicit importRelease mode and admin registration.
A fork in a private GitLab project needs the token secret described under
Fork sources.
A custom fork, or an official version whose upgrade was refused, stays on its
registered closure; opening it in the releases tab shows Upgrade closure,
which adopts a newly published revision without changing existing intent pins.
Existing intents keep the release they were created with. To stop offering a release, follow Roll back a channel.
Release contents in the authoring UI
A release's closure is browsable read-only, so authors can see what a pinned intent resolves rather than only the mutable library:
GET /aidlc-releases/{releaseId}/blocks[?type=agent,stage]lists the closure's blocks by type, in theGET /blocks/{type}shape withsource: "release"and thereleaseId, plus the release's workflow.GET /aidlc-releases/{releaseId}/blocks/{type}/{blockId}returns one block with its body and script. Each object must be one the manifest lists, and its bytes must match the recorded digest, or the read is a409.- Both read the digest-verified closure and never the SYSTEM rows. An admin may read any registered release; anybody else only a selectable one, and an unknown and a hidden release get the same
404.
In the app:
- Admin → AI-DLC releases: each registered release has a Contents view listing its workflow and its blocks by type.
- Block library: with pinning on, the stable release's blocks of the current type appear below the library, read-only and labelled with the release id.
?release=<id>shows another release instead. A release block opens read-only in the block editor. A library block with the same id is flagged, because it replaces the release's block in pinned intents. - Workflows: the stable release's workflow is listed, read-only.
- Stage editor: the lead, support, reviewer, artifact, sensor and stage pickers include the stable release's blocks. Each id is listed once, in the order a pinned intent resolves it: the user library, then the release. A pinned intent never reads the SYSTEM rows, so a block only SYSTEM has is not offered while a release is in play; without a release the pickers list the library as before. Each option is labelled with its source. A typed id that no picker lists is still accepted.
- Workflow composer, adding a stage: under a selected version, the stage palette offers library and release stages only. A placed stage the release does not have is still shown.
- Workflow composer: for a user workflow, the plan check and compiled view pass
?libraryRelease=<stable>. This previews the live workflow the way an intent created now would resolve it: the closure replaces the SYSTEM rows, the user library overlays it atV#latest, and SYSTEM placements resolve from the closure. So a custom stage that names an agent only the release ships checks clean, as it runs.libraryReleasecannot be combined withrelease, which previews a pinned intent's own closure and workflow snapshot.
Copying a release agent into the default library to make it pickable is no longer needed. Such a copy replaces the release's agent in every pinned intent.
Selection and rollback
With pinning enabled, the intent API resolves the selected release or the stable channel and stamps that identity onto the intent. Non-admin callers receive only the release fields needed for selection. The admin release page supports registration, promotion, visibility changes, channel management, and closure upgrade while preserving revision checks.
Roll back a channel
To stop offering a newly promoted release, move the affected channel to a previously eligible release or clear the channel through the release API. The change affects future intent selection only; an existing intent continues to use its stored release ID and closure digest. If the current release must no longer be selectable, demote it after moving or clearing every channel that points to it. Channel and release revisions are compare-and-swap guards; retry with the latest revision if another administrator changed the record.
Do not delete a release closure to roll back selection. The immutable objects are required by intents already pinned to that release. Keep the closure and registry record available until those intents no longer need to resolve it.
Execution gates and policy
The gate layer turns authored release policy into runtime checks. It is active only for a verified release closure; an unpinned intent continues on the legacy plan and prompt path.
Checkpoints and receipts
confirm_summary and request_plan_approval are author-only MCP tools. Each
parks a human question with fixed answer choices and writes an attempt-scoped
RECEIPT# row when approved. Release-mode artifact writes are stamped with the
active authorization. A bounded completion ladder gives a non-compliant stage
one repair turn, then reports a gate finding or a rewind-eligible failure.
Receipts use the existing execution table and remain auditable without deleting
them. Checkpoint prompts use the existing question and validation gate kinds.
Plan Approval's runtime handler checks authorization at the completion boundary, so it approximates the upstream pre-write guard rather than providing the same guarantee. Promotion remains blocked until the current build registers the outcome-gate handler; once available, stored and legacy records are re-evaluated from their verified closures without re-import.
The completion ladder persists its per-attempt repair counter before it starts a repair turn. If that write fails, the stage fails rewindably with the original checkpoint finding; it does not run an uncounted repair or report success.
Gate findings and sensors
The shared gate-precondition evaluator combines artifact, checkpoint, review, and sensor findings and determines whether the gate blocks or allows an override. The orchestrator presents findings at the validation gate; an allowed override is recorded with a receipt and timeline event.
fire_on: write uses the post-agent changed-file sweep. fire_on: gate runs a
separate pass after reviewer repairs, against declared deliverables and their
final bytes. Blocking findings hold the gate when one exists; otherwise the
stage fails with a rewind-eligible reason.
Scope policy
review_caplowers or removes reviewer strength;review_class: advisoryruns one terminal review and carries findings to the gate.change_control: relaxedrecords changed approved inputs and continues.strictopens a two-choice question before the next stage proceeds. After reconfirmation, the stage does not spawn its CLI until the attempt-scopedchange-reconfirmreceipt is persisted. A failed write returns a rewindableFAILEDstate; an existing receipt for the same attempt is reused idempotently.learnings: offwithholds the learning-write tools.onoffers a learning question at an existing approval gate; this is an approximation of a separate upstream turn. The orchestrator sends the answer through AgentCore'srecord-learningcommand, registered by the HTTP dispatcher.skeleton: offskips the walking-skeleton ceremony while retaining the ordinary approval gate.AGENT.maxTurnsmaps to the native OpenCode turn limit; it remains inert on CLIs that expose no equivalent.
Per-intent AI-DLC settings
A scope's Guard Policy, Plan Approval, collaborators and project type can be
overridden for ONE intent. The settings are ordinary draft selection state: they
travel in the same PATCH /projects/{projectId}/intents/{intentId} body as
scope and composedGrid, under the same draft-revision CAS, and are flushed by
the same barrier Start already awaits. There is no separate route and no second
write path.
- Only the settings the pinned release's chosen scope AUTHORS are offered
(
plan.aidlcSettingsAuthored). A release that authors none — unpinned, 2.3.3, 2.8.2, 2.9.0 — offers nothing, stores nothing and resolves exactly the policy it resolved before. - Only DELTAS from that scope's default are stored. A value equal to the default
is not an override, so it is not persisted; the consequence is that an explicit
choice which happens to equal the default is not retained across a later scope
change, the same semantics
composedGridalready has relative toscope. - The settings are only ever validated against a selection that arrived in the
same request: a body carrying settings without
scopeorcomposedGridis refused with400 selection_required_with_settings. - A setting the new selection does not author is dropped and named in the
response, so the UI can say which choice a scope change withdrew. A value
outside the capability registry's own value set, or of the wrong authored type,
is refused with
400 aidlc_setting_invalid. - Settings are DRAFT-only. A write once the run has started answers
409 settings_locked, which is the platform's half of the dialect annex's refusal of a mid-run settings change. No MCP tool can write one. - Each changed key appends one
v2.intent.settings.changedtimeline event naming the authenticated member whose write changed it. The append is best-effort after persistence, like the other event appends. - The recorded overrides reach the run, not only the draft: the orchestrator
walk, every stage and resume dispatch and both of AgentCore's own stage
resolutions project them through one shared contract
(
shared/intent-methodology.js). - A stage that would have asked for a plan approval and did not carries an advisory gate notice saying whether the pinned release's named scope turns Plan Approval off by default or the intent turned it off before the run started. The notice names nobody; attribution is on the intent timeline.
Build-and-test loop-back
Releases that ship the construction protocol (2.6.18 and later) let build-and-test send the work back to code generation. Upstream does this autonomously, up to three times per intent. Here a gated intent's human decides, at the validation gate build-and-test already has; an autonomous intent takes the jump.
The capability is classified approximated: a gated intent is offered the
loop-back at the gate rather than having it taken for it, and scopes that run code
generation per unit get a gate note instead of the option. Under Construction
Autonomy Mode: autonomous the jump IS taken for the intent, recorded with the
protocol's Autonomous loop-back N per construction protocol module answer and
bounded by the same three per intent.
- The agent records a recommendation through the
loopBackRecommendedfield ofemit_stage_note. The platform writes the reason on the stage's own row; the gate reads it and clears it once the gate is answered, so a recommendation is offered once. A failed write fails the tool call. - The gate offers a third option,
loop-back, when the stage immediately before build-and-test (passing over skipped stages) is code generation and the intent has used fewer than three loop-backs. The tally lives on the execution META row. It is updated in the same transaction as the code-generation reset, keyed by the gate id, so a replayed step does not count twice and a rewound run starts new ids. - Choosing it resets code generation and build-and-test. Their attempts are
bumped, which makes earlier plan-approval and review receipts unreachable.
Code generation then runs fresh with the agent's reason and the reviewer's
feedback in its prompt. If a reset fails, code generation is marked
FAILEDand the run fails in a rewindable state. - The answer is recorded as
rejected, so orchestrator code that predates the loop-back reads it as request-changes. The answer API rejects any other status for a loop-back, and rejects loop-back on a gate that does not offer it. - At the cap, and in scopes that run code generation per unit (classic, enterprise, feature, mvp, workshop), the gate shows the recommendation and why the option is not offered. Those cases use request-changes or rewind. An autonomous intent halts to that same human gate in both cases: a recommendation is never approved over.
- An autonomous intent takes the jump only in answer to the recommendation itself. Any blocking finding — a blocking gate sensor that did not pass, a missing required output, or a reviewer still not ready — opens the human gate instead, because rewinding would discard the finding and silently re-run the work. Advisory findings do not withhold the jump. Missing evidence does, as it keeps a gate from being waived: outputs that could not be observed, or learning candidates that could not be read, open the human gate. So do learning candidates waiting for review, which the gate puts to the human.
- The autonomous jump is stored the way a human one is: build-and-test's
validation gate row, under a run-scoped id, written already answered
(
rejected,loop-back, the marker as the answer, no human author) with the agent's reason. Code generation resumes from that row, so the same resets, archive of both stages, reason in the prompt and cap tally apply, and a relaunch takes a new decision rather than reusing the earlier one. - The autonomous gate creation and answer, and each stage reset, verify the
run's ownership in the transaction that writes them. Gate creation and resets
also require the intent to remain
RUNNING; recording the decision never parks it. A cancel or relaunch between those writes retires the old run without further resets, cap spending or re-dispatch. A reset that committed while the old run still owned the intent remains part of its history. - An autonomous jump does not run on to build-and-test unattended. Code generation runs again under a new attempt, so it asks for Plan Approval again, and its validation gate opens for a human again: the grant never waives a gate that carries Plan Approval, and the reset leaves no earlier approval in force. The jump replaces the human's loop-back answer at build-and-test, not those two stops.
- An execution started before this release keeps opening the human gate for an offered loop-back, so an execution already parked on that gate replays the same operations after the deployment. A relaunch starts a new execution, which takes the jump.
- Residual: the jump, like upstream's, depends on the agent's recommendation. A build-and-test stage that succeeds with failing tests but records no recommendation and raises no finding has clean evidence, so an autonomous intent approves it. A blocking results sensor is what turns those failures into a halt.
An answered gate whose durable callback failed to resume can be retried through
the intent's Resume action. Callback-consumption markers and answered gate state
prevent a duplicate resume; an expired callback transitions the intent to a
rewind-recoverable FAILED state rather than leaving it indefinitely WAITING.
Construction autonomy
Releases that ship the construction protocol also carry Construction Autonomy
Mode: the human's standing permission to complete the remaining construction
stage gates without stopping. The capability is classified native — the grant,
its two-value vocabulary, the first-stage carve-out and the halt-and-ask set are
all reproduced.
- The grant is per-intent and two-valued. Absent and
gatedboth read as gated; onlyautonomouswaives anything. It is frozen onto the intent at create by the human creating it, or escalated later by an explicit human answer: thegrant-autonomyoption, offered at the one construction gate that always stays human. The answer API rejects it on a gate that does not offer it. The release listing reportsconstructionAutonomyfor each release, read from the record's stored protocol evidence, so the create page offers the opt-in only for a selected release that has it. The non-admin listing never re-verifies a closure, so a record whose stored evidence predates the protocol entries listsfalsethere until an admin listing or a promotion re-verifies and caches it. The opt-in is then hidden, never wrongly offered, and creating an intent still decides from the release's closure. - Once given, the grant holds for the rest of the intent, rewinds included, until the intent is cancelled. Cancelling clears it and records who withdrew it and when on the grant's provenance, so a rewind after a cancel relaunches the intent gated. Cancel is only accepted while the intent is parked or failed: a waived gate never parks, so an autonomous run can be cancelled once it halts at a human gate, a question or a failure. Every gate with a finding still halts and asks.
- It lives on its own META attribute,
constructionGateAutonomy. The per-section unit-lane ladder keepsconstructionAutonomyMode: that question asks only about parallel lane batching, and reading it here would waive gates the human was never asked about. - A waived gate is never opened. The approved answer is synthesized and the run
takes the ordinary approval path, so the durable record is the ordinary
attempt-scoped
stage-approvalreceipt, carryingautonomous: trueand the protocol's marker input. Thev2.gate.auto_approvedtimeline event is best-effort telemetry on top of that receipt, never the record itself. The grant's own provenance — who, when, and whether at create or at a gate — is durable too, asconstructionGateAutonomyGrant. - The halt-and-ask set is reproduced in full: the plan's first non-skipped construction stage with a sequential gate, every Code Generation Plan Approval, every fan-out approval, a stage failure, a blocking gate sensor, and a loop-back recommendation all still open a human gate. The one exception is an offered loop-back with no blocking finding, which takes the autonomous jump described under the build-and-test loop-back; it is never approved. A recommendation at the bound, or with no code generation to go back to, opens the gate. So does a gate with learning candidates waiting for the learnings ritual, and a gate whose stage outputs the runner could not observe: "no finding" is only read as clean when the outputs were actually checked. On an intent with a grant, each construction gate re-reads the intent before deciding, so a deleted intent, a cancelled run, or a run taken over by another orchestrator (a rewind relaunch) stops the walk instead of approving. An intent without a grant, and every gate outside construction, skips that read and keeps its durable history.
- Two deviations, both stricter than upstream: the gate-precondition evaluation
runs in full on a waived gate, so ANY finding (advisory included) keeps it
from being approved; and a terminal adversarial
NOT-READYblocks a waived gate instead of being auto-approved. On a gate the grant does not cover, that same verdict stays an advisory finding andapproveremains on offer, exactly as before. An offered loop-back is the one place an advisory finding does not open the human gate: only a blocking finding withholds the autonomous jump, and the advisory findings it is taken over are stored on the jump's gate row. - Residual: the grant governs only the once-per-workflow sequential gates.
Per-unit stages inside a parallel section keep their own ceremony — the
walking-skeleton gate and the section autonomy ladder — so a scope with a unit
DAG still batches its lane approvals there. In those scopes the gate that
always stays human is the first sequential construction gate after the lanes
(for example build-and-test), and that is where
grant-autonomyis offered. Non-construction phases are untouched. - Residual: a waived gate judges the stage's evidence, not its test results. A build-and-test stage that succeeds with failing tests but raises no finding and records no loop-back recommendation has clean evidence, so an autonomous intent approves it. A blocking results sensor is what turns those failures into a halt.
Persona sessions
Pinned releases that declare pipeline or mob stages, or subagent stages
with supports, dispatch each persona in its own serial session. For subagent
this applies only when the release closure ships
core/aidlc-common/protocols/stage-protocol-ensemble.md; a closure without that
file keeps a subagent stage on one delegated session however many supports it
declares, so 2.3.3 reverse-engineering is unaffected. A stage whose plan
resolved no policy also stays on the single-session path, because the validation
gate could not report persona evidence for it.
Each session receives a role-scoped brief:
pipeline links see earlier outputs, support personas see the lead draft without
sibling contributions, and the lead integration sees the collected contributions.
The reviewer remains a separate read-only session.
Contributions are written as persona-scoped artifacts and timeline events. The
platform stamps the contributor identity from the trusted session scope, so one
persona cannot create or overwrite another persona's evidence. A failed support
session is retried once with a reduced brief; if it still produces no evidence,
the run records a gap and continues, and the gap is reported at the validation
gate. An integration that produced no evidence is reported the same way, as
ensemble_integration_missing. A timed-out CLI child is killed and its exit
awaited before retry or gap handling.
One failure does not degrade to a gap. If the stage's persona receipt history
cannot be read, no persona session is dispatched and the platform cannot say
whether the declared personas ran, so the validation gate records
ensemble_evidence_unavailable: blocking and not overridable. There is no
override-and-approve for it, because a waiver would waive something nobody can
describe. Requesting changes re-runs the stage, which re-reads the receipts, so
the run is never stuck; a receipt store that stays unreadable leaves the stage
unapprovable until it recovers. A persona session, retry included, starts
only if a full 45-minute session still fits the stage budget of 6.5 hours; the
budget restarts with each run of the stage, including a resume, and is additionally
bounded by the runtime session's remaining lifetime, because serial stages share
one session. A session that does not fit is recorded as a gap, and a budget that
cut every collaborator, or that cut the integration, blocks the validation gate
overridably. Mob dissent is triaged for at most two
rounds and any maintained objection is shown verbatim at the existing validation
gate. Only the lead session can ask the human: no persona session, the
integrator included, is given ask_question, and judgment-class objections are
quoted at the validation gate instead.
get_team_knowledge and record_team_knowledge use the space's shared
knowledge. Persona identity scopes authorship; it does not create a private
knowledge namespace for each persona. Identity checks apply through supported
tool calls; they are workflow controls, not an isolation boundary against a
compromised AgentCore runtime identity, which remains trusted.
Persona sessions apply to release-pinned intents only. Standard deployments enable release selection by default, but do not approve or select a new version automatically. There is no separate switch for persona sessions: to stop running persona sessions, do not pin intents to a release that declares these modes.
agent-team remains explicitly unimplemented. Build-and-Test loop-back is a
separate runtime behavior with its own handler; persona sessions do not add a
loop-back gate option.
Verification
Run the offline compatibility and golden-digest suite after importer or mapper changes:
npm run test:aidlc-compatibility
The suite reads vendored fixtures and requires no network or cloud credentials.