Merge branch 'main' into feature/instructions

Author: harmjeff

.github/workflows/pull-request-lint.yml

@@ -82,6 +82,8 @@ jobs:
     permissions:
       pull-requests: read
     if: always()
+    env:
+      GH_TOKEN: ${{ github.token }}
     steps:
       - run: |
           PR_NUMBER="${{ needs.get-pr-info.outputs.pr_number }}"
@@ -92,6 +94,7 @@ jobs:
           echo "::debug::HALT_MERGES value: $HALT_MERGES"
           echo "::debug::This PR number: $PR_NUMBER"
           echo "::group::Open Release Pull Requests"
+          gh pr list --state "open" --repo "${{ github.repository }}" --json "number,headRefName"
           OPEN_RELEASES=$(gh pr list --state "open" --repo "${{ github.repository }}" --json "number,headRefName" | \
               jq '[.[] | select(.headRefName | startswith("release/"))]')
           echo $OPEN_RELEASES

.github/workflows/release-pr.yml

@@ -70,8 +70,8 @@ jobs:
                 VERSION="${MAJOR}.${MINOR}.${PATCH}"
                 echo "WARNING: No conventional commits detected — falling back to patch bump: $VERSION"
               else
-                echo "::warning::No conventional commits and no existing tags — nothing to release"
-                exit 0
+                echo "::error::No conventional commits and no existing tags — nothing to release"
+                exit 1
               fi
             fi
           fi
@@ -109,34 +109,58 @@ jobs:
 
           # Check if branch already exists (local or remote)
           if git ls-remote --exit-code --heads origin "$BRANCH" &>/dev/null; then
-            echo "::warning::Branch '$BRANCH' already exists. A release PR may already be open — close it and delete the branch to re-run."
-            exit 0
+            echo "::error::Branch '$BRANCH' already exists. A release PR may already be open — close it and delete the branch to re-run."
+            exit 1
           fi
 
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
 
           git add CHANGELOG.md
           if git diff --cached --quiet CHANGELOG.md; then
-            echo "No changes to CHANGELOG.md"
-            exit 0
+            echo "::error::No releasable commits since last tag – CHANGELOG.md is already up to date. Push new conventional commits or adjust the requested version before rerunning this workflow."
+            exit 1
           fi
 
           git checkout -b "$BRANCH"
           git commit -m "docs: update changelog for $TAG"
           git push origin "$BRANCH"
 
-          LABEL_FLAG=""
-          if gh label list --search "release" --json name --jq '.[].name' | grep -qx "release"; then
-            LABEL_FLAG="--label release"
-          fi
+          label_args=()
+          for LABEL in "release"; do
+            if gh label list --search "$LABEL" --json name --jq '.[].name' | grep -qx "$LABEL"; then
+              label_args+=("--label" "$LABEL")
+            fi
+          done
 
+          # Draft PR because the github-actions[bot] does not trigger a pull_request_target workflow
           gh pr create \
-            --title "release: $TAG" \
+            --title "docs: update changelog for $TAG" \
+            --draft \
             --body "$(cat <<EOF
-          ## Release $TAG
+          # Release $TAG
+
+          > [!WARNING]  
+          > All other pull requests are blocked until merged or closed
+          
+          This pull request is for the $TAG release.
+
+          ## Checklist (in order)
+          
+          1. [ ] Mark the pull request "Ready for review" to trigger required workflows
+          2. [ ] Inspect the CHANGELOG.md and "Approve" or "Reject" the pending [CodeBuild](https://github.com/awslabs/aidlc-workflows/actions/workflows/codebuild.yml) GitHub Action
+          3. [ ] Evaluate the artifacts
+          4. [ ] Review the pull request (if approved set the "Merge when ready")
+
+          ## Post Merge
+
+          * [ ] Verify $TAG tag
+          * [ ] Approve "Approve" or "Reject" the pending [CodeBuild](https://github.com/awslabs/aidlc-workflows/actions/workflows/codebuild.yml) GitHub Action
+          * [ ] Review the drafted release artifacts for completion
+          * [ ] Publish the release
 
-          This PR updates CHANGELOG.md for the $TAG release.
+          > [!CAUTION]
+          > Simply closing this will block a subsequent $TAG release, so delete the branch or reopen the pull request if necessary
 
           **When merged**, the merge commit will be automatically tagged as \`$TAG\`, which triggers:
           - \`release.yml\` — creates a draft GitHub Release with the rules zip
@@ -145,4 +169,4 @@ jobs:
           After both workflows complete, review and publish the draft release.
           EOF
           )" \
-            $LABEL_FLAG
+            "${label_args[@]}"

README.md

@@ -529,7 +529,7 @@ Here's the general flow once an extension is enabled:
 The workflow currently ships with a baseline security extension. 
 
 > [!IMPORTANT]
-> The security extension rules are based on the [OWASP Top 10](https://owasp.org/www-project-top-ten/) and have been tested through controlled experimentation (see [PR #80](https://github.com/awslabs/aidlc-workflows/pull/80)). They are provided as a directional reference for building effective security rules within AI-DLC workflows. Each organization should build, customize, and thoroughly test their own security rules before deploying in production workflows.
+> The security extension rules are provided as a directional reference for building effective security rules within AI-DLC workflows. Each organization should build, customize, and thoroughly test their own security rules before deploying in production workflows.
 
 ```
 aws-aidlc-rule-details/

aidlc-rules/aws-aidlc-rule-details/common/error-handling.md

@@ -130,7 +130,7 @@
 - **Solution**: Clearly mark as **HUMAN TASK**, provide instructions
 - **Wait**: For user confirmation before proceeding
 
-### Code Planning Errors
+### Code Generation Planning Errors
 
 **Error**: Code generation plan is incomplete
 - **Cause**: Missing design artifacts, unclear requirements

aidlc-rules/aws-aidlc-rule-details/common/process-overview.md

@@ -9,7 +9,7 @@
 
 ## The Three-Phase Lifecycle:
 • **INCEPTION PHASE**: Planning and architecture (Workspace Detection + conditional phases + Workflow Planning)
-• **CONSTRUCTION PHASE**: Design, implementation, build and test (per-unit design + Code Planning/Generation + Build & Test)
+• **CONSTRUCTION PHASE**: Design, implementation, build and test (per-unit design + Code Generation + Build & Test)
 • **OPERATIONS PHASE**: Placeholder for future deployment and monitoring workflows
 
 ## The Adaptive Workflow:

aidlc-rules/aws-aidlc-rule-details/common/terminology.md

@@ -10,13 +10,13 @@
 - 🟡 **OPERATIONS PHASE** - Deployment & Monitoring (future expansion)
 
 **Stage**: An individual workflow activity within a phase
-- Examples: Context Assessment stage, Requirements Assessment stage, Code Planning stage
+- Examples: Context Assessment stage, Requirements Assessment stage, Code Generation stage
 - Each stage has specific prerequisites, steps, and outputs
 - Stages can be ALWAYS-EXECUTE or CONDITIONAL
 
 **Usage Examples**:
 - ✅ "The CONSTRUCTION phase contains 7 stages"
-- ✅ "The Code Planning stage is always executed"
+- ✅ "The Code Generation stage is always executed"
 - ✅ "We're in the INCEPTION phase, executing the Requirements Assessment stage"
 - ❌ "The Requirements Assessment phase" (should be "stage")
 - ❌ "The CONSTRUCTION stage" (should be "phase")
@@ -49,8 +49,7 @@
 - NFR Requirements (CONDITIONAL, per-unit)
 - NFR Design (CONDITIONAL, per-unit)
 - Infrastructure Design (CONDITIONAL, per-unit)
-- Code Planning (ALWAYS)
-- Code Generation (ALWAYS)
+- Code Generation (ALWAYS) — includes Part 1: Planning and Part 2: Generation
 - Build and Test (ALWAYS)
 
 **Outputs**: Design artifacts, NFR implementations, code, tests
@@ -73,8 +72,7 @@
 - **Workspace Detection**: Initial analysis of workspace state and project type
 - **Requirements Analysis**: Gathering requirements (depth varies based on complexity)
 - **Workflow Planning**: Creating execution plan for which phases to run
-- **Code Planning**: Creating detailed implementation plans for code generation
-- **Code Generation**: Generating actual code based on plans and prior artifacts
+- **Code Generation**: Single stage with two parts — Part 1 (Planning) creates detailed implementation plans, Part 2 (Generation) generates actual code based on plans and prior artifacts
 - **Build and Test**: Building all units and executing comprehensive testing
 
 ### Conditional Stages
@@ -156,7 +154,7 @@ Examples:
 - Units Planning → Units Generation
 - Unit Design Planning → Unit Design Generation
 - NFR Planning → NFR Generation
-- Code Planning → Code Generation
+- Code Generation Part 1 (Planning) → Code Generation Part 2 (Generation)
 
 ### Depth Levels
 - **Minimal**: Quick, focused execution for simple changes

aidlc-rules/aws-aidlc-rule-details/common/workflow-changes.md

@@ -85,7 +85,7 @@ Users may request changes to the execution plan or phase execution during the wo
 
 **Handling**:
 1. **Assess Impact**: Identify all stages that depend on the stage to be restarted
-2. **Warn User**: "Restarting Application Design will require redoing: Units Planning, Units Generation, per-unit design (all units), Code Planning, Code Generation. Confirm?"
+2. **Warn User**: "Restarting Application Design will require redoing: Units Planning, Units Generation, per-unit design (all units), Code Generation. Confirm?"
 3. **Get Explicit Confirmation**: User must understand full impact
 4. **If Confirmed**:
    - Archive all affected artifacts

aidlc-rules/aws-aidlc-rule-details/construction/code-generation.md

@@ -87,7 +87,7 @@ This stage generates code for each unit of work through two integrated parts:
 - [ ] Mark the approval status clearly
 
 ## Step 9: Update Progress
-- [ ] Mark Code Planning complete in `aidlc-state.md`
+- [ ] Mark Code Generation Part 1 (Planning) complete in `aidlc-state.md`
 - [ ] Update the "Current Status" section
 - [ ] Prepare for transition to Code Generation