feat(labkit): make projection sync history useful

labkit/src/labkit/gen_workflows.py

@@ -142,6 +142,8 @@ def _pr_body_block(config: PublishConfig) -> str:
           {{
             echo "## What this sync releases"; echo
             for note in "${{added[@]}}"; do cat "$note"; echo; done
+            echo "## Included source changes"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
             echo "<details><summary>Projection provenance</summary>"; echo
             echo "Generated from \\`{config.source.repo}@$SOURCE_COMMIT\\`."
             echo "Review provenance, tests, and examples before merging."; echo
@@ -150,6 +152,8 @@ def _pr_body_block(config: PublishConfig) -> str:
     return f"""          git add -A
           body_file="$(mktemp)"
           {{
+            echo "## Included source changes"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
             echo "## Projection provenance"; echo
             echo "Generated from \\`{config.source.repo}@$SOURCE_COMMIT\\`."
             echo "Review the operator contract, provenance, and compatibility before merging."
@@ -229,18 +233,44 @@ def render_sync_upstream(config: PublishConfig) -> str:
             echo "stale=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+          changes_file="$RUNNER_TEMP/{config.project}-source-changes.md"
+          if [[ -n "$current_commit" ]] &&
+             git -C intelligence-flow merge-base --is-ancestor "$current_commit" "$source_commit"; then
+            git -C intelligence-flow log --reverse \\
+              --format='- [%h](https://github.com/{config.source.repo}/commit/%H) %s' \\
+              "$current_commit..$source_commit" -- {lab_path} > "$changes_file"
+          else
+            git -C intelligence-flow show -s \\
+              --format='- [%h](https://github.com/{config.source.repo}/commit/%H) %s' \\
+              "$source_commit" > "$changes_file"
+          fi
+          if [[ ! -s "$changes_file" ]]; then
+            printf -- '- [%s](https://github.com/{config.source.repo}/commit/%s) Projected source state\\n' \\
+              "${{source_commit:0:12}}" "$source_commit" > "$changes_file"
+          fi
+          source_subject="$(git -C intelligence-flow show -s --format=%s "$source_commit" | cut -c1-72)"
+          change_count="$(grep -c '^-' "$changes_file" || true)"
+          change_suffix=""
+          if (( change_count > 1 )); then
+            change_suffix=" (+$((change_count - 1)) earlier changes)"
+          fi
+          sync_title="Sync {config.display_name}: $source_subject$change_suffix"
           python3 -m labkit project \\
             --config intelligence-flow/{lab_path}/publish.config.json \\
             --repo public-repo \\
             --source-commit "$source_commit" \\
             --write
           echo "source_commit=$source_commit" >> "$GITHUB_OUTPUT"
+          echo "changes_file=$changes_file" >> "$GITHUB_OUTPUT"
+          echo "sync_title=$sync_title" >> "$GITHUB_OUTPUT"
           echo "stale=false" >> "$GITHUB_OUTPUT"
       - name: Open generated pull request
         if: steps.generate.outputs.stale != 'true'
         env:
           GH_TOKEN: ${{{{ steps.app-token.outputs.token }}}}
           SOURCE_COMMIT: ${{{{ steps.generate.outputs.source_commit }}}}
+          SOURCE_CHANGES_FILE: ${{{{ steps.generate.outputs.changes_file }}}}
+          SYNC_TITLE: ${{{{ steps.generate.outputs.sync_title }}}}
         shell: bash
         run: |
           cd public-repo
@@ -255,11 +285,19 @@ def render_sync_upstream(config: PublishConfig) -> str:
           git config user.name "${{{{ steps.app-token.outputs.app-slug }}}}[bot]"
           git config user.email "${{{{ steps.app-token.outputs.app-slug }}}}[bot]@users.noreply.github.com"
           git switch -c "$branch"
-          git commit -m "Sync {config.display_name} from {config.sync.source_label} @ $short"
+          commit_file="$(mktemp)"
+          {{
+            echo "$SYNC_TITLE"; echo
+            echo "Included source changes:"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
+            echo "Source-Repository: {config.source.repo}"
+            echo "Source-Commit: $SOURCE_COMMIT"
+          }} > "$commit_file"
+          git commit -F "$commit_file"
           git push --force --set-upstream origin "$branch"
           if [[ -z "$existing" ]]; then
             pr_url="$(gh pr create --base main --head "$branch" \\
-              --title "Sync {config.display_name} from {config.sync.source_label} @ $short" \\
+              --title "$SYNC_TITLE" \\
               --body-file "$body_file")"
             echo "Opened generated PR: $pr_url"
           else

labkit/tests/test_labkit_gen.py

@@ -90,6 +90,19 @@ def test_sync_drives_the_engine_uniformly():
         assert "sync-intelligence-flow" in sync  # shared concurrency group
 
 
+def test_sync_commits_explain_projected_source_changes():
+    for config_file in CONFIGS:
+        sync = render_sync_upstream(load_config(config_file))
+        assert "## Included source changes" in sync
+        assert "SOURCE_CHANGES_FILE" in sync
+        assert 'sync_title="Sync ' in sync
+        assert "Source-Repository:" in sync
+        assert "Source-Commit: $SOURCE_COMMIT" in sync
+        assert 'git commit -F "$commit_file"' in sync
+        assert '--title "$SYNC_TITLE"' in sync
+        assert " from Intelligence Flow @ $short" not in sync
+
+
 def test_value_map_preserves_narrow_trigger_path():
     dispatcher = render_publish_dispatcher(_config("14-product-value-projection"))
     assert '"labs/14-product-value-projection/value-map/**"' in dispatcher

labs/12-product-engineering-loop/.labkit/generated/sync-upstream.yml

@@ -69,18 +69,44 @@ jobs:
             echo "stale=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+          changes_file="$RUNNER_TEMP/boatstack-source-changes.md"
+          if [[ -n "$current_commit" ]] &&
+             git -C intelligence-flow merge-base --is-ancestor "$current_commit" "$source_commit"; then
+            git -C intelligence-flow log --reverse \
+              --format='- [%h](https://github.com/operatorstack/intelligence-flow/commit/%H) %s' \
+              "$current_commit..$source_commit" -- labs/12-product-engineering-loop > "$changes_file"
+          else
+            git -C intelligence-flow show -s \
+              --format='- [%h](https://github.com/operatorstack/intelligence-flow/commit/%H) %s' \
+              "$source_commit" > "$changes_file"
+          fi
+          if [[ ! -s "$changes_file" ]]; then
+            printf -- '- [%s](https://github.com/operatorstack/intelligence-flow/commit/%s) Projected source state\n' \
+              "${source_commit:0:12}" "$source_commit" > "$changes_file"
+          fi
+          source_subject="$(git -C intelligence-flow show -s --format=%s "$source_commit" | cut -c1-72)"
+          change_count="$(grep -c '^-' "$changes_file" || true)"
+          change_suffix=""
+          if (( change_count > 1 )); then
+            change_suffix=" (+$((change_count - 1)) earlier changes)"
+          fi
+          sync_title="Sync Boatstack: $source_subject$change_suffix"
           python3 -m labkit project \
             --config intelligence-flow/labs/12-product-engineering-loop/publish.config.json \
             --repo public-repo \
             --source-commit "$source_commit" \
             --write
           echo "source_commit=$source_commit" >> "$GITHUB_OUTPUT"
+          echo "changes_file=$changes_file" >> "$GITHUB_OUTPUT"
+          echo "sync_title=$sync_title" >> "$GITHUB_OUTPUT"
           echo "stale=false" >> "$GITHUB_OUTPUT"
       - name: Open generated pull request
         if: steps.generate.outputs.stale != 'true'
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           SOURCE_COMMIT: ${{ steps.generate.outputs.source_commit }}
+          SOURCE_CHANGES_FILE: ${{ steps.generate.outputs.changes_file }}
+          SYNC_TITLE: ${{ steps.generate.outputs.sync_title }}
         shell: bash
         run: |
           cd public-repo
@@ -108,6 +134,8 @@ jobs:
           {
             echo "## What this sync releases"; echo
             for note in "${added[@]}"; do cat "$note"; echo; done
+            echo "## Included source changes"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
             echo "<details><summary>Projection provenance</summary>"; echo
             echo "Generated from \`operatorstack/intelligence-flow@$SOURCE_COMMIT\`."
             echo "Review provenance, tests, and examples before merging."; echo
@@ -119,11 +147,19 @@ jobs:
           git config user.name "${{ steps.app-token.outputs.app-slug }}[bot]"
           git config user.email "${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com"
           git switch -c "$branch"
-          git commit -m "Sync Boatstack from Intelligence Flow Labs @ $short"
+          commit_file="$(mktemp)"
+          {
+            echo "$SYNC_TITLE"; echo
+            echo "Included source changes:"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
+            echo "Source-Repository: operatorstack/intelligence-flow"
+            echo "Source-Commit: $SOURCE_COMMIT"
+          } > "$commit_file"
+          git commit -F "$commit_file"
           git push --force --set-upstream origin "$branch"
           if [[ -z "$existing" ]]; then
             pr_url="$(gh pr create --base main --head "$branch" \
-              --title "Sync Boatstack from Intelligence Flow Labs @ $short" \
+              --title "$SYNC_TITLE" \
               --body-file "$body_file")"
             echo "Opened generated PR: $pr_url"
           else

labs/12-product-engineering-loop/boatstack-distribution/release-notes/2026-08-01-readable-projection-history.md

@@ -0,0 +1,6 @@
+### Make projection history readable
+
+Generated sync pull requests and commits now use the latest relevant source
+commit subject instead of only showing an opaque source hash. Their bodies list
+every included Boatstack source commit with GitHub links and retain the full
+source repository and commit as provenance trailers.

labs/14-product-value-projection/.labkit/generated/sync-upstream.yml

@@ -69,18 +69,44 @@ jobs:
             echo "stale=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+          changes_file="$RUNNER_TEMP/value-map-source-changes.md"
+          if [[ -n "$current_commit" ]] &&
+             git -C intelligence-flow merge-base --is-ancestor "$current_commit" "$source_commit"; then
+            git -C intelligence-flow log --reverse \
+              --format='- [%h](https://github.com/operatorstack/intelligence-flow/commit/%H) %s' \
+              "$current_commit..$source_commit" -- labs/14-product-value-projection > "$changes_file"
+          else
+            git -C intelligence-flow show -s \
+              --format='- [%h](https://github.com/operatorstack/intelligence-flow/commit/%H) %s' \
+              "$source_commit" > "$changes_file"
+          fi
+          if [[ ! -s "$changes_file" ]]; then
+            printf -- '- [%s](https://github.com/operatorstack/intelligence-flow/commit/%s) Projected source state\n' \
+              "${source_commit:0:12}" "$source_commit" > "$changes_file"
+          fi
+          source_subject="$(git -C intelligence-flow show -s --format=%s "$source_commit" | cut -c1-72)"
+          change_count="$(grep -c '^-' "$changes_file" || true)"
+          change_suffix=""
+          if (( change_count > 1 )); then
+            change_suffix=" (+$((change_count - 1)) earlier changes)"
+          fi
+          sync_title="Sync Value Map: $source_subject$change_suffix"
           python3 -m labkit project \
             --config intelligence-flow/labs/14-product-value-projection/publish.config.json \
             --repo public-repo \
             --source-commit "$source_commit" \
             --write
           echo "source_commit=$source_commit" >> "$GITHUB_OUTPUT"
+          echo "changes_file=$changes_file" >> "$GITHUB_OUTPUT"
+          echo "sync_title=$sync_title" >> "$GITHUB_OUTPUT"
           echo "stale=false" >> "$GITHUB_OUTPUT"
       - name: Open generated pull request
         if: steps.generate.outputs.stale != 'true'
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           SOURCE_COMMIT: ${{ steps.generate.outputs.source_commit }}
+          SOURCE_CHANGES_FILE: ${{ steps.generate.outputs.changes_file }}
+          SYNC_TITLE: ${{ steps.generate.outputs.sync_title }}
         shell: bash
         run: |
           cd public-repo
@@ -91,6 +117,8 @@ jobs:
           git add -A
           body_file="$(mktemp)"
           {
+            echo "## Included source changes"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
             echo "## Projection provenance"; echo
             echo "Generated from \`operatorstack/intelligence-flow@$SOURCE_COMMIT\`."
             echo "Review the operator contract, provenance, and compatibility before merging."
@@ -101,11 +129,19 @@ jobs:
           git config user.name "${{ steps.app-token.outputs.app-slug }}[bot]"
           git config user.email "${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com"
           git switch -c "$branch"
-          git commit -m "Sync Value Map from Intelligence Flow @ $short"
+          commit_file="$(mktemp)"
+          {
+            echo "$SYNC_TITLE"; echo
+            echo "Included source changes:"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
+            echo "Source-Repository: operatorstack/intelligence-flow"
+            echo "Source-Commit: $SOURCE_COMMIT"
+          } > "$commit_file"
+          git commit -F "$commit_file"
           git push --force --set-upstream origin "$branch"
           if [[ -z "$existing" ]]; then
             pr_url="$(gh pr create --base main --head "$branch" \
-              --title "Sync Value Map from Intelligence Flow @ $short" \
+              --title "$SYNC_TITLE" \
               --body-file "$body_file")"
             echo "Opened generated PR: $pr_url"
           else

labs/15-pitot/.labkit/generated/sync-upstream.yml

@@ -69,18 +69,44 @@ jobs:
             echo "stale=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+          changes_file="$RUNNER_TEMP/pitot-source-changes.md"
+          if [[ -n "$current_commit" ]] &&
+             git -C intelligence-flow merge-base --is-ancestor "$current_commit" "$source_commit"; then
+            git -C intelligence-flow log --reverse \
+              --format='- [%h](https://github.com/operatorstack/intelligence-flow/commit/%H) %s' \
+              "$current_commit..$source_commit" -- labs/15-pitot > "$changes_file"
+          else
+            git -C intelligence-flow show -s \
+              --format='- [%h](https://github.com/operatorstack/intelligence-flow/commit/%H) %s' \
+              "$source_commit" > "$changes_file"
+          fi
+          if [[ ! -s "$changes_file" ]]; then
+            printf -- '- [%s](https://github.com/operatorstack/intelligence-flow/commit/%s) Projected source state\n' \
+              "${source_commit:0:12}" "$source_commit" > "$changes_file"
+          fi
+          source_subject="$(git -C intelligence-flow show -s --format=%s "$source_commit" | cut -c1-72)"
+          change_count="$(grep -c '^-' "$changes_file" || true)"
+          change_suffix=""
+          if (( change_count > 1 )); then
+            change_suffix=" (+$((change_count - 1)) earlier changes)"
+          fi
+          sync_title="Sync Pitot: $source_subject$change_suffix"
           python3 -m labkit project \
             --config intelligence-flow/labs/15-pitot/publish.config.json \
             --repo public-repo \
             --source-commit "$source_commit" \
             --write
           echo "source_commit=$source_commit" >> "$GITHUB_OUTPUT"
+          echo "changes_file=$changes_file" >> "$GITHUB_OUTPUT"
+          echo "sync_title=$sync_title" >> "$GITHUB_OUTPUT"
           echo "stale=false" >> "$GITHUB_OUTPUT"
       - name: Open generated pull request
         if: steps.generate.outputs.stale != 'true'
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           SOURCE_COMMIT: ${{ steps.generate.outputs.source_commit }}
+          SOURCE_CHANGES_FILE: ${{ steps.generate.outputs.changes_file }}
+          SYNC_TITLE: ${{ steps.generate.outputs.sync_title }}
         shell: bash
         run: |
           cd public-repo
@@ -91,6 +117,8 @@ jobs:
           git add -A
           body_file="$(mktemp)"
           {
+            echo "## Included source changes"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
             echo "## Projection provenance"; echo
             echo "Generated from \`operatorstack/intelligence-flow@$SOURCE_COMMIT\`."
             echo "Review the operator contract, provenance, and compatibility before merging."
@@ -101,11 +129,19 @@ jobs:
           git config user.name "${{ steps.app-token.outputs.app-slug }}[bot]"
           git config user.email "${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com"
           git switch -c "$branch"
-          git commit -m "Sync Pitot from Intelligence Flow @ $short"
+          commit_file="$(mktemp)"
+          {
+            echo "$SYNC_TITLE"; echo
+            echo "Included source changes:"; echo
+            cat "$SOURCE_CHANGES_FILE"; echo
+            echo "Source-Repository: operatorstack/intelligence-flow"
+            echo "Source-Commit: $SOURCE_COMMIT"
+          } > "$commit_file"
+          git commit -F "$commit_file"
           git push --force --set-upstream origin "$branch"
           if [[ -z "$existing" ]]; then
             pr_url="$(gh pr create --base main --head "$branch" \
-              --title "Sync Pitot from Intelligence Flow @ $short" \
+              --title "$SYNC_TITLE" \
               --body-file "$body_file")"
             echo "Opened generated PR: $pr_url"
           else

labs/15-pitot/pitot-distribution/release-notes/2026-08-01-readable-projection-history.md

@@ -0,0 +1,6 @@
+### Make projection history readable
+
+Generated sync pull requests and commits now use the latest relevant source
+commit subject instead of only showing an opaque source hash. Their bodies list
+every included Pitot source commit with GitHub links and retain the full source
+repository and commit as provenance trailers.