feat: export native AI-DLC workspaces by jeromevdl · Pull Request #403 · aws-samples/sample-collaborative-ai-dlc

jeromevdl · 2026-08-13T07:38:41Z

Summary

Native workspace export

Export a stable Collaborative AI-DLC checkpoint as a runnable native AI-DLC workspace for Claude, Codex, Kiro CLI, Kiro IDE, or OpenCode.
Reconstruct native State Version 7 with the workflow scope, completed and skipped stages, and the correct resume point.
Materialize generated Markdown work products in their canonical native phase, stage, and per-unit paths.
Reconstruct pending and answered *-questions.md files from human gates when no persisted Markdown artifact exists.
Preserve arbitrary custom workflow compositions by registering their native scope definition, stage frontmatter, stage-graph.json, and scope-grid.json.
Include custom project rules and repository URL/branch metadata. Source code and credentials are intentionally excluded.
Reconstruct multi-unit Construction state: complete Bolt DAG, merged-unit receipts, autonomy mode, and next-unit resume point.
- Reconstruct native audit stage events and runtime-graph.json.

Version and snapshot fidelity

Resolve the native harness from the intent's pinned AI-DLC commit, fetch it on demand, and cache the immutable archive in S3.
Support both legacy aidlc-docs/ and newer aidlc/spaces/... workspace layouts by inspecting the selected harness.
Preserve pinned stage versions and compatibility with legacy workflow snapshots.
Detect whether the pinned harness ships aidlc-workspace-sync.ts; otherwise provide manual sibling-repository setup.
Use the root Terraform AI-DLC pin consistently across Lambdas.

Platform integration

Add the export API, archive generation, presigned downloads, S3 lifecycle cleanup, IAM permissions, and deployment support.
Increase export Lambda capacity for uncached harness retrieval.

User experience

Add a workspace download action with harness selection:

Warn that subsequent local work will not synchronize back into Collaborative AI-DLC traceability:

Provide post-download repository and workspace setup commands when the exported checkpoint is entering Construction or a later phase:

Verification

pre-commit hook: 125 test files, 2,490 tests passed
frontend production build passed
intents Lambda build passed
frontend lint and formatting checks passed
intents lint and formatting checks passed
Add native runtime recompilation checks against pinned 2.3.3 and current v2, see screenshots.
Tested live against "legacy" AIDLC (ba0cfe999856033ecb909a9135b46fe10811bf55) and a multi-repo space with newer version (83ed7a812c4024904f2c5e4d744e28077e0a5acd)

Fixes #400

JWThewes

The feature direction looks useful, but I think the checkpoint and provenance guarantees need tightening before this is safe to merge. The inline comments cover the concrete changes I am asking for.

JWThewes · 2026-08-14T07:40:18Z

+    // while the archive is assembled, producing an internally inconsistent
+    // checkpoint.
+    if (intentId && httpMethod === 'POST' && path?.endsWith('/export')) {
+      const records = await store.getExecutionRecords(intentId, { includeOutputs: false });


This status check does not actually make the export a stable snapshot. We read the execution partition here, then resolve the plan and read Neptune artifacts later; a WAITING intent can be answered or edited in between. That can give us old stage/question state with newer artifacts in the same ZIP. Can we either export from an immutable revision, or capture and recheck a revision/status token immediately before upload and fail or retry if anything changed?

I will create some immutable checkpoints at the end of each stage, so that it will also permit the export while in status RUNNING (exporting the latest stable checkpoint).

Addressed in 5a75ccf by introducing lightweight immutable workflow checkpoints at completed stage boundaries. Checkpoints reference content-addressed artifact versions rather than storing ZIPs or artifact bodies. RUNNING exports use the latest checkpoint, while WAITING and terminal exports use live state with a final consistency recheck. This also enables safe exports during active execution without mixed snapshots.

JWThewes · 2026-08-14T07:40:18Z

+        const exported = await createNativeExport({
+          s3,
+          bucket: ARTIFACTS_BUCKET(),
+          upstreamRef: meta.aidlcRepoRef || AIDLC_REPO_REF(),


I do not think meta.aidlcRepoRef is an execution pin yet. We persist it at intent creation and use it here, but AgentCore still reads the deployment-wide AIDLC_REPO_REF; after a pin update an existing intent can continue under the new ref and then export the old harness. Please thread the intent's ref through execution and preserve matching block/workflow snapshots, or record the actual ref per stage and reject mixed-ref exports.

Addressed in 47d71f8. aidlcRepoRef is now an execution pin, not only an export pin. The intent’s resolved SHA and exact supporting block versions are stored on META, forwarded through orchestration, and used by AgentCore for the conductor and methodology library. Stage rows record the effective SHA, and export rejects mixed-revision executions. This covers parked sessions that resume on a newer AgentCore image.

JWThewes · 2026-08-14T07:40:18Z

+  (meta.repos ?? []).map((repository) => {
+    const provider = meta.repoProviders?.[repository] || meta.gitProvider || 'github';
+    return {
+      name: repositoryName(repository),


We lose the canonical repository identity here. org-a/api and org-b/api are both valid project repositories, but both become api, so repos.json and the setup commands target the same directory. The reverse-engineering projector has the opposite problem and rejects owner/repo as a path segment. Could we keep owner/repo as the ID and derive a collision-safe local directory name once, then use that mapping everywhere?

Addressed in 0871912. Exports now preserve canonical repository IDs and derive one deterministic local directory mapping. Unique basenames remain unchanged; collisions such as org-a/api and org-b/api become org-a_api and org-b_api. The same mapping is used by repos.json, intent metadata, CodeKB paths, the export API, and frontend clone commands. Regression tests cover the duplicate-basename case.

JWThewes · 2026-08-14T07:40:18Z

+};
+
+const loadDistribution = async ({ s3, bucket, upstreamRef, harness }) => {
+  if (!isCommitSha(upstreamRef)) {


aidlc_repo_ref is documented and implemented elsewhere as SHA, tag, or branch, so this makes export fail for an otherwise supported deployment configuration. If export requires immutability, can we resolve the configured ref to a full SHA when the intent is created and persist that SHA, rather than rejecting tags and branches here?

Addressed in 47d71f8. Configured tags and branches are resolved to a full commit SHA before intent creation and seeding. The immutable SHA is then used consistently for runtime snapshots, execution, checkpoints, and native export.
Manually verified with v2.3.0: META, the running stage, and export-manifest.json all used 29a31f7899731b53f2b8d7f76cd223f9a8a25859.

JWThewes · 2026-08-14T07:40:18Z

+    batches: parsed.batches,
+    skipMatrix: unitPlan.skipMatrix ?? {},
+    walkingSkeleton: unitPlan.walkingSkeleton ?? null,
+    autonomyMode: hasRecordedAutonomyMode ? unitPlan.autonomyMode : 'gated',


This changes workflow semantics by making a choice the user has not made. In cloud state, autonomyMode is intentionally null until the post-skeleton ladder; defaulting it to gated also causes us to emit an AUTONOMY_MODE_SET audit event that never happened. Please preserve unset and let the native workflow ask the ladder question.

Addressed in 486a420. I had some issues with Kiro when letting unset, it didn't ask for the autonomy mode.

JWThewes · 2026-08-14T07:40:18Z

+    setExporting(true);
+    setActionError(null);
+    try {
+      const result = await intentsService.exportWorkflow(projectId, intentId, harness);


The API returns warnings specifically for provenance and runtime compatibility, but we never surface result.warnings here. In the no-setup case the user will not see them at all. Can we show warnings before or alongside the download, and add a test for the legacy-ref warning?

Addressed in 86cd45a:

frontend/src/pages/IntentView.tsx:222 opens the dialog when warnings exist, even without setup instructions.

frontend/src/components/intent/NativeExportSetupDialog.tsx:119 renders every warning in the amber alert. Lines 109–115 provide warning-only title/description.

JWThewes · 2026-08-14T07:40:18Z

+      </AlertDialog>
+
+      <AlertDialog
+        open={constructionExport !== null}


Suggestion: could we move this setup dialog into a NativeExportSetupDialog component and drive the four modes from shared step data? IntentView is now about 1,000 lines and the extraction, launch, and continue steps are repeated across each branch, which will make future setup changes easy to miss in one mode.

Addressed in 86cd45a, creation of the NativeExportSetupDialog

jeromevdl · 2026-08-17T10:19:36Z

f968f86 adds immutable, commit-pinned methodology catalogs in S3. Seed writes the structured catalog before replacing SYSTEM records, and native export uses the intent’s historical catalog when the current SYSTEM revision differs. Missing catalogs can be rebuilt from the pinned commit. Manually verified with an intent pinned to 83ed7a8… after SYSTEM was reseeded to v2.3.0 (29a31f…); export succeeded and retained 83ed7a8… in the manifest.

jeromevdl marked this pull request as ready for review August 13, 2026 15:21

jeromevdl requested review from JWThewes, eipasteur, leandrodamascena and svozza as code owners August 13, 2026 15:21

jeromevdl added 8 commits August 13, 2026 17:23

feat: export native AI-DLC workspaces

542ba59

feat: persist workspace project type

4871ac4

fix: preserve native export checkpoints

e81a5d9

feat: improve workspace setup guidance

5785fa0

fix: propagate AI-DLC ref to lambdas

080991b

fix: adapt multi-repo workspace setup

cead72d

fix: reconstruct native runtime graph

69370a8

fix: increase export lambda capacity

877ff40

jeromevdl force-pushed the feat/workflow-exporter branch from 21b5173 to 877ff40 Compare August 13, 2026 15:24

fix: harden native export distribution loading

424f16f

JWThewes requested changes Aug 14, 2026

View reviewed changes

jeromevdl added 7 commits August 14, 2026 17:10

feat: export running workflows from checkpoints

5a75ccf

fix: pin AI-DLC methodology per intent

47d71f8

fix: preserve repository identity in native exports

0871912

fix: preserve unset construction autonomy

486a420

fix: surface native export warnings

86cd45a

test: cover legacy export warning

9c39b2f

fix: preserve methodology catalogs across reseeds

f968f86

jeromevdl requested a review from JWThewes August 17, 2026 10:19

jeromevdl mentioned this pull request Aug 18, 2026

Feat: develop a unit externally #407

Draft

jeromevdl added 2 commits August 19, 2026 14:08

fix: do not automatically trigger download when selecting the harness

f9dfc3b

docs: explain native workspace exports

4b0d11e

Uh oh!

Conversation

jeromevdl commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Native workspace export

Version and snapshot fidelity

Platform integration

User experience

Verification

Uh oh!

JWThewes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeromevdl Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeromevdl commented Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jeromevdl commented Aug 13, 2026 •

edited

Loading

jeromevdl Aug 14, 2026 •

edited

Loading