Merge pull request 'chore(release): v09.00.00' (#140 ) from dev into main

chore(release): bump to 09.00.00
PHPDoc standard, CI enforcement, updates_xml_build fixes. Authored-by: Moko Consulting Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-05-26 04:33:40 +00:00 · 2026-05-25 23:32:42 -05:00 · 2026-05-26 04:29:33 +00:00 · 2026-05-26 04:29:29 +00:00 · 2026-05-25 23:26:07 -05:00 · 2026-05-25 23:12:12 -05:00
22 changed files with 2543 additions and 252 deletions
@@ -263,6 +263,7 @@ jobs:
        run: |
          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
          php /tmp/moko-platform-api/cli/badge_update.php --path . --version "${VERSION}" 2>/dev/null || true
+          php /tmp/moko-platform-api/cli/version_check.php --path . --fix 2>/dev/null || true

      - name: "Step 5: Write update stream"
        if: >-
@@ -306,9 +307,7 @@ jobs:
      # -- STEP 6: Create tag ---------------------------------------------------
      - name: "Step 6: Create git tag"
        if: >-
-          steps.version.outputs.skip != 'true' &&
-          steps.check.outputs.tag_exists != 'true' &&
-          steps.version.outputs.is_minor == 'true'
+          steps.version.outputs.skip != 'true'
        run: |
          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
          # Only create the major release tag if it doesn't exist yet
@@ -462,110 +461,35 @@ jobs:
          SHA256_ZIP=$(sha256sum "/tmp/${ZIP_NAME}" | cut -d' ' -f1)
          SHA256_TAR=$(sha256sum "/tmp/${TAR_NAME}" | cut -d' ' -f1)

-          # -- Delete existing assets with same name before uploading ------
+          # -- Get existing assets for cleanup --------------------------------
          ASSETS=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
            "${API_BASE}/releases/${RELEASE_ID}/assets" 2>/dev/null || echo "[]")
-          for ASSET_NAME in "$ZIP_NAME" "$TAR_NAME"; do
+
+          # -- Create per-file .sha256 checksum files -------------------------
+          echo "${SHA256_ZIP}  ${ZIP_NAME}" > "/tmp/${ZIP_NAME}.sha256"
+          echo "${SHA256_TAR}  ${TAR_NAME}" > "/tmp/${TAR_NAME}.sha256"
+
+          # -- Upload packages + checksums to release tag --------------------
+          for ASSET in "${ZIP_NAME}" "${TAR_NAME}" "${ZIP_NAME}.sha256" "${TAR_NAME}.sha256"; do
+            [ ! -f "/tmp/${ASSET}" ] && continue
+            # Delete existing asset with same name
            ASSET_ID=$(echo "$ASSETS" | python3 -c "
          import sys,json
          assets = json.load(sys.stdin)
          for a in assets:
-              if a['name'] == '${ASSET_NAME}':
+              if a['name'] == '${ASSET}':
                  print(a['id']); break
          " 2>/dev/null || true)
-            if [ -n "$ASSET_ID" ]; then
-              curl -sf -X DELETE -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-                "${API_BASE}/releases/${RELEASE_ID}/assets/${ASSET_ID}" 2>/dev/null || true
-            fi
+            [ -n "$ASSET_ID" ] && curl -sf -X DELETE -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+              "${API_BASE}/releases/${RELEASE_ID}/assets/${ASSET_ID}" 2>/dev/null || true
+            # Upload
+            curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary @"/tmp/${ASSET}" \
+              "${API_BASE}/releases/${RELEASE_ID}/assets?name=${ASSET}" > /dev/null 2>&1 || true
          done

-          # -- Upload both to release tag ----------------------------------
-          curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-            -H "Content-Type: application/octet-stream" \
-            --data-binary @"/tmp/${ZIP_NAME}" \
-            "${API_BASE}/releases/${RELEASE_ID}/assets?name=${ZIP_NAME}" > /dev/null 2>&1 || true
-
-          curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-            -H "Content-Type: application/octet-stream" \
-            --data-binary @"/tmp/${TAR_NAME}" \
-            "${API_BASE}/releases/${RELEASE_ID}/assets?name=${TAR_NAME}" > /dev/null 2>&1 || true
-
-          # -- Update updates.xml with both download formats ---------------
-          if [ -f "updates.xml" ]; then
-            ZIP_URL="${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/download/${RELEASE_TAG}/${ZIP_NAME}"
-            TAR_URL="${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/download/${RELEASE_TAG}/${TAR_NAME}"
-
-            # Use Python to update only the stable entry's downloads + sha256
-            export PY_ZIP_URL="$ZIP_URL" PY_TAR_URL="$TAR_URL" PY_SHA="$SHA256_ZIP"
-            python3 << 'PYEOF'
-          import re, os
-
-          with open("updates.xml") as f:
-              content = f.read()
-
-          zip_url = os.environ["PY_ZIP_URL"]
-          tar_url = os.environ["PY_TAR_URL"]
-          sha = os.environ["PY_SHA"]
-
-          # Find the stable update block and replace its downloads + sha256
-          def replace_stable(m):
-              block = m.group(0)
-              # Replace downloads block
-              new_downloads = (
-                  "    <downloads>\n"
-                  f"      <downloadurl type=\"full\" format=\"zip\">{zip_url}</downloadurl>\n"
-                  "    </downloads>"
-              )
-              block = re.sub(r'    <downloads>.*?</downloads>', new_downloads, block, flags=re.DOTALL)
-              # Add or replace sha256
-              if '<sha256>' in block:
-                  block = re.sub(r'    <sha256>.*?</sha256>', f'    <sha256>{sha}</sha256>', block)
-              else:
-                  block = block.replace('</downloads>', f'</downloads>\n    <sha256>{sha}</sha256>')
-              return block
-
-          content = re.sub(
-              r'  <update>.*?<tag>stable</tag>.*?</update>',
-              replace_stable,
-              content,
-              flags=re.DOTALL
-          )
-
-          with open("updates.xml", "w") as f:
-              f.write(content)
-          PYEOF
-
-            CURRENT_BRANCH="${{ github.ref_name }}"
-            git add updates.xml
-            git commit -m "chore(release): ZIP + tar.gz for ${VERSION} [skip ci]" \
-              --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>" || true
-            git push || true
-
-            # Sync updates.xml to main via direct API (always runs — may be on version/XX branch)
-            GA_TOKEN="${{ secrets.GA_TOKEN }}"
-            API="${GITEA_URL:-https://git.mokoconsulting.tech}/api/v1/repos/${{ github.repository }}"
-
-            FILE_SHA=$(curl -sf -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/contents/updates.xml?ref=main" | jq -r '.sha // empty')
-
-            if [ -n "$FILE_SHA" ]; then
-              CONTENT=$(base64 -w0 updates.xml)
-              curl -sf -X PUT -H "Authorization: token ${GA_TOKEN}" \
-                -H "Content-Type: application/json" \
-                "${API}/contents/updates.xml" \
-                -d "$(jq -n \
-                  --arg content "$CONTENT" \
-                  --arg sha "$FILE_SHA" \
-                  --arg msg "chore: sync updates.xml ${VERSION} [skip ci]" \
-                  --arg branch "main" \
-                  '{content: $content, sha: $sha, message: $msg, branch: $branch}'
-                )" > /dev/null 2>&1 \
-                && echo "updates.xml synced to main via API" \
-                || echo "WARNING: failed to sync updates.xml to main"
-            else
-              echo "WARNING: could not get updates.xml SHA from main"
-            fi
-          fi
+          # updates.xml already handled by Step 5 (updates_xml_build.php with preserve logic)

          echo "### Packages" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
@@ -576,73 +500,33 @@ jobs:
          echo "| Release | \`${RELEASE_TAG}\` | |" >> $GITHUB_STEP_SUMMARY
          echo "| Download | [${ZIP_NAME}](${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/download/${RELEASE_TAG}/${ZIP_NAME}) |" >> $GITHUB_STEP_SUMMARY

-      # -- STEP 8b: Update release description with changelog + SHA ----------------
-      - name: "Step 8b: Update release body with changelog and SHA"
+      # -- STEP 8b: Update release description with changelog ----------------------
+      - name: "Step 8b: Update release body"
        if: steps.version.outputs.skip != 'true'
        run: |
          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          EXT_ELEMENT="${{ steps.updates.outputs.ext_element }}"
-          EXT_TYPE="${{ steps.updates.outputs.ext_type }}"
-          EXT_FOLDER="${{ steps.updates.outputs.ext_folder }}"
+          MOKO_CLI="/tmp/moko-platform-api/cli"

-          # Build TYPE_PREFIX to match Step 8's ZIP naming
-          EXT_ELEMENT=$(echo "$EXT_ELEMENT" | sed -E 's/^(pkg_|com_|mod_|plg_[a-z]+_|tpl_|lib_)//')
-          TYPE_PREFIX=""
-          case "${EXT_TYPE}" in
-            plugin)    TYPE_PREFIX="plg_${EXT_FOLDER}_" ;;
-            module)    TYPE_PREFIX="mod_" ;;
-            component) TYPE_PREFIX="com_" ;;
-            template)  TYPE_PREFIX="tpl_" ;;
-            library)   TYPE_PREFIX="lib_" ;;
-            package)   TYPE_PREFIX="pkg_" ;;
-          esac
-          ZIP_NAME="${TYPE_PREFIX}${EXT_ELEMENT}-${VERSION}.zip"
-          TAR_NAME="${TYPE_PREFIX}${EXT_ELEMENT}-${VERSION}.tar.gz"
-
-          # Get SHA from the built files
-          SHA256_ZIP=""
-          [ -f "/tmp/${ZIP_NAME}" ] && SHA256_ZIP=$(sha256sum "/tmp/${ZIP_NAME}" | cut -d' ' -f1)
-          SHA256_TAR=""
-          [ -f "/tmp/${TAR_NAME}" ] && SHA256_TAR=$(sha256sum "/tmp/${TAR_NAME}" | cut -d' ' -f1)
-
-          # Extract latest changelog entry (strip the ## header to avoid duplicate)
-          CHANGELOG=""
-          if [ -f "CHANGELOG.md" ]; then
-            CHANGELOG=$(sed -n "/^## \[*${VERSION}/,/^## \[*[0-9]/p" CHANGELOG.md | sed '$d' | sed '1d')
-            [ -z "$CHANGELOG" ] && CHANGELOG=$(sed -n '/^## /,/^## /p' CHANGELOG.md | sed '$d' | sed '1d' | head -30)
-          fi
-
-          # Build release body (single header, no duplicate from changelog)
-          BODY="## ${VERSION} ($(date +%Y-%m-%d))\n\n"
-          if [ -n "$CHANGELOG" ]; then
-            BODY="${BODY}${CHANGELOG}\n\n"
-          fi
-          BODY="${BODY}---\n\n### Checksums\n\n"
-          BODY="${BODY}| File | SHA-256 |\n|------|--------|\n"
-          [ -n "$SHA256_ZIP" ] && BODY="${BODY}| \`${ZIP_NAME}\` | \`${SHA256_ZIP}\` |\n"
-          [ -n "$SHA256_TAR" ] && BODY="${BODY}| \`${TAR_NAME}\` | \`${SHA256_TAR}\` |\n"
-
-          # Get release ID and update body
-          RELEASE_ID=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-            "${API_BASE}/releases/tags/${RELEASE_TAG}" 2>/dev/null | \
-            python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
-
-          if [ -n "$RELEASE_ID" ] && [ "$RELEASE_ID" != "None" ]; then
-            python3 -c "
-          import json, urllib.request
-          body = '''$(printf '%b' "$BODY")'''
-          data = json.dumps({'body': body}).encode()
-          req = urllib.request.Request(
-              '${API_BASE}/releases/${RELEASE_ID}',
-              data=data,
-              headers={'Authorization': 'token ${{ secrets.GA_TOKEN }}', 'Content-Type': 'application/json'},
-              method='PATCH'
-          )
-          urllib.request.urlopen(req)
-          " 2>/dev/null && echo "Release body updated with changelog + SHA" >> $GITHUB_STEP_SUMMARY
-          fi
+          php ${MOKO_CLI}/release_body_update.php \
+            --path . --version "${VERSION}" --tag "${RELEASE_TAG}" \
+            --token "${{ secrets.GA_TOKEN }}" \
+            --gitea-url "${GITEA_URL}" --org "${GITEA_ORG}" --repo "${GITEA_REPO}" \
+            2>/dev/null || {
+            # Fallback: simple body update if CLI not available
+            API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+            RELEASE_ID=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+              "${API_BASE}/releases/tags/${RELEASE_TAG}" 2>/dev/null | \
+              python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+            if [ -n "$RELEASE_ID" ] && [ "$RELEASE_ID" != "None" ]; then
+              BODY="## ${VERSION} ($(date +%Y-%m-%d))\n\nChecksum files attached as \`*.sha256\` assets."
+              curl -sf -X PATCH -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+                -H "Content-Type: application/json" \
+                "${API_BASE}/releases/${RELEASE_ID}" \
+                -d "{\"body\":\"${BODY}\"}" > /dev/null 2>&1
+            fi
+          }
+          echo "Release body updated" >> $GITHUB_STEP_SUMMARY

      # -- STEP 9: Mirror to GitHub (stable only) --------------------------------
      - name: "Step 9: Mirror release to GitHub"
@@ -124,16 +124,16 @@ jobs:
          echo "### PHPCS" >> $GITHUB_STEP_SUMMARY
          echo "PSR-12 compliance: passed" >> $GITHUB_STEP_SUMMARY

-      - name: "PHPStan (Level 2)"
-        continue-on-error: true
+      - name: "PHPStan (Level 6)"
        run: |
-          vendor/bin/phpstan analyse -c phpstan.neon --no-progress --error-format=github 2>&1 || {
-            echo "::warning::PHPStan found type errors (advisory)"
+          vendor/bin/phpstan analyse -c phpstan.neon --no-progress --memory-limit=512M --error-format=github 2>&1 || {
+            echo "::error::PHPStan found type errors"
            echo "### PHPStan" >> $GITHUB_STEP_SUMMARY
            echo "Static analysis errors detected. Run \`composer phpstan\` locally." >> $GITHUB_STEP_SUMMARY
+            exit 1
          }
          echo "### PHPStan" >> $GITHUB_STEP_SUMMARY
-          echo "Static analysis: advisory (level 0)" >> $GITHUB_STEP_SUMMARY
+          echo "Static analysis (level 6): passed" >> $GITHUB_STEP_SUMMARY

      - name: "Psalm"
        continue-on-error: true
@@ -177,11 +177,14 @@ jobs:

      - name: "PHPUnit (PHP ${{ matrix.php }})"
        run: |
-          vendor/bin/phpunit --testdox 2>&1
-          {
-            echo "### PHPUnit (PHP ${{ matrix.php }})"
-            echo "All tests passed."
-          } >> $GITHUB_STEP_SUMMARY
+          vendor/bin/phpunit --testdox 2>&1 || {
+            echo "::error::PHPUnit tests failed"
+            echo "### PHPUnit (PHP ${{ matrix.php }})" >> $GITHUB_STEP_SUMMARY
+            echo "Tests failed. Run \`vendor/bin/phpunit --testdox\` locally." >> $GITHUB_STEP_SUMMARY
+            exit 1
+          }
+          echo "### PHPUnit (PHP ${{ matrix.php }})" >> $GITHUB_STEP_SUMMARY
+          echo "All tests passed." >> $GITHUB_STEP_SUMMARY

  # ═══════════════════════════════════════════════════════════════════════
  # Gate 3 — Self-Health (Dogfood)
@@ -18,6 +18,32 @@ Version format: `XX.YY.ZZ` (zero-padded semver).

 ## [Unreleased]

+## [09.00.00] - 2026-05-26
+
+### Added
+- PHPDoc on Priority 1 Enterprise classes (CliFramework, adapters, ApiClient)
+- Wiki: Coding-Standards page with PHPDoc standard, PHPCS exclusions, file patterns
+- CI: PHPStan enforced at level 6 (was advisory), PHPUnit blocks on failure
+
+### Fixed
+- `updates_xml_build.php`: cascade entries down to lower channels — stable now writes all 5 entries instead of wiping them
+- `updates_xml_build.php`: separate Joomla stability tags (`dev`, `rc`) from Gitea release tags (`development`, `release-candidate`) — download URLs now point to correct release assets
+- `updates_xml_build.php`: only emit `<client>site</client>` for templates and modules, not packages or components
+- `updates_xml_build.php`: preservation logic matches Joomla tag names when deciding which existing entries to keep
+
+## [08.00.00] - 2026-05-26
+
+### Changed
+- PHPStan: level 5 → 6 (401 baselined, 0 new errors)
+- Branch protection: 5 required checks enabled on main
+- Workflows synced to all governed repos (72+ repos across 3 orgs)
+- Flushed 44 stale runners from Gitea admin (3 active remain)
+
+### Fixed
+- PHPStan level 3→4: removed 13 dead properties, 41 defensive patterns baselined
+- PHPStan level 4→5: fixed metrics `increment()` bug (labels passed as value param)
+- PHPStan level 5→6: 360 missing array generic types baselined
+
 ## [07.00.00] - 2026-05-25

 ### Added
@@ -53,7 +53,6 @@ class BulkJoomlaTemplate extends CliFramework
    public const VERSION     = '04.06.10';

    private GitPlatformAdapter $adapter;
-    private AuditLogger $logger;
    private Config $config;

    protected function configure(): void
@@ -85,7 +84,6 @@ class BulkJoomlaTemplate extends CliFramework
            return 1;
        }

-        $this->logger = new AuditLogger('joomla_template');
        $org = $this->getArgument('--org', self::DEFAULT_ORG);
        $platform = $this->adapter->getPlatformName();
        $this->log("Platform: {$platform} | Organization: {$org}", 'INFO');
@@ -66,9 +66,6 @@ class BulkSync extends CliFramework
    private AuditLogger $logger;
    private CheckpointManager $checkpoints;
    private MetricsCollector $metrics;
-    private SecurityValidator $security;
-    private PluginFactory $pluginFactory;
-    private ProjectTypeDetector $typeDetector;
    private Config $config;

    /** Set to true by signal handler or rate-limit detection to abort the sync loop gracefully. */
@@ -204,7 +201,6 @@ class BulkSync extends CliFramework
            $this->logger      = new AuditLogger('bulk_sync');
            $this->metrics     = new MetricsCollector();
            $this->checkpoints = new CheckpointManager('.checkpoints');
-            $this->security    = new SecurityValidator();
            $this->synchronizer = new RepositorySynchronizer(
                $this->api,
                $this->logger,
@@ -215,8 +211,6 @@ class BulkSync extends CliFramework
            );

            // Initialize plugin system
-            $this->pluginFactory = new PluginFactory($this->logger, $this->metrics);
-            $this->typeDetector = new ProjectTypeDetector($this->logger);

            $this->log("✓ Enterprise components initialized for platform: {$platform}", 'INFO');
            return true;
@@ -288,7 +282,7 @@ class BulkSync extends CliFramework
            }
        }

-        return array_values(array_merge($priority, $rest));
+        return array_merge($priority, $rest);
    }

    /**
@@ -58,8 +58,6 @@ class RepoCleanup extends CliFramework

    private ApiClient $api;
    private GitPlatformAdapter $adapter;
-    private AuditLogger $logger;
-    private MetricsCollector $metrics;
    protected bool $dryRun = false;
    private float $startTime;

@@ -99,8 +97,6 @@ class RepoCleanup extends CliFramework
            return 1;
        }

-        $this->logger  = new AuditLogger('repo_cleanup');
-        $this->metrics = new MetricsCollector('repo_cleanup');

        $this->logMsg("🧹 MokoStandards Repository Cleanup v" . self::VERSION);
        $this->logMsg("Organization: {$org}");
@@ -48,7 +48,6 @@ class JoomlaRelease extends CliFramework
    ];

    private ApiClient   $api;
-    private AuditLogger $logger;
    private \MokoEnterprise\GitPlatformAdapter $adapter;

    protected function configure(): void
@@ -76,7 +75,6 @@ class JoomlaRelease extends CliFramework
        $config       = Config::load();
        $this->adapter = PlatformAdapterFactory::create($config);
        $this->api    = $this->adapter->getApiClient();
-        $this->logger = new AuditLogger('joomla_release');

        if ($repo !== '') {
            $path = $this->cloneRepo($repo);
@@ -194,29 +194,35 @@ $stabilitySuffixMap = [
 	'development' => '-dev',
 ];

+// Joomla <tags><tag> values — maps to Joomla's stabilityTagToInteger()
 $stabilityTagMap = [
 	'stable'      => 'stable',
 	'rc'          => 'rc',
 	'beta'        => 'beta',
 	'alpha'       => 'alpha',
+	'development' => 'dev',
+];
+
+// Gitea release tag names (used in download/info URLs)
+$releaseTagMap = [
+	'stable'      => 'stable',
+	'rc'          => 'release-candidate',
+	'beta'        => 'beta',
+	'alpha'       => 'alpha',
 	'development' => 'development',
 ];

 // -- Build update entries -----------------------------------------------------
-$releaseTag = $stabilityTagMap[$stability] ?? $stability;
-
 // For the primary entry: apply suffix if not stable
 $primarySuffix = $stabilitySuffixMap[$stability] ?? '';
 $primaryVersion = $version . $primarySuffix;

-$downloadUrl = "{$giteaUrl}/{$org}/{$repo}/releases/download/{$releaseTag}/{$typePrefix}{$extElement}-{$primaryVersion}.zip";
-$infoUrl = "{$giteaUrl}/{$org}/{$repo}/releases/tag/{$releaseTag}";
-
-// Build client tag
+// Build client tag — only needed for templates and modules (site vs admin).
+// Packages and components don't use client; plugins use folder instead.
 $clientTag = '';
 if (!empty($extClient)) {
 	$clientTag = "    <client>{$extClient}</client>";
-} elseif ($extType === 'module' || $extType === 'plugin') {
+} elseif (in_array($extType, ['template', 'module'])) {
 	$clientTag = '    <client>site</client>';
 }

@@ -282,41 +288,44 @@ function buildEntry(
 }

 // -- Determine which channels to write ----------------------------------------
-// Stable cascades to all channels; pre-releases only write their level and below
-// Each channel gets its own suffixed version:
-//   development -> 04.01.00-dev
-//   alpha       -> 04.01.00-alpha
-//   beta        -> 04.01.00-beta
-//   rc          -> 04.01.00-rc
-//   stable      -> 04.01.00
+// Stable cascades to all channels; pre-releases cascade down to lower channels.
+// Each channel entry represents "latest release available at this stability or higher".
+// When stable releases, ALL channels point to stable (it's the newest for everyone).
+// When RC releases, rc/beta/alpha/dev point to RC; stable is preserved.
+// When dev releases, only dev is updated; everything else is preserved.
 $allChannels = ['development', 'alpha', 'beta', 'rc', 'stable'];
 $stabilityIndex = array_search($stability === 'development' ? 'development' : $stability, $allChannels);
 if ($stabilityIndex === false) $stabilityIndex = 4; // default to stable

-// Write only the current channel entry (not cascade)
-// Each channel release only creates its own entry; preserved entries handle other channels
+// Write entries for the current channel AND all lower channels (cascade down)
+// All cascaded entries point to the CURRENT release (the highest stability being built)
 $entries = [];
-$channelName = $allChannels[$stabilityIndex];
-$channelSuffix = $stabilitySuffixMap[$channelName] ?? '';
-$channelVersion = $version . $channelSuffix;
-$channelTag = $stabilityTagMap[$channelName] ?? $channelName;
-$channelDownloadUrl = "{$giteaUrl}/{$org}/{$repo}/releases/download/{$channelTag}/{$typePrefix}{$extElement}-{$channelVersion}.zip";
-$channelInfoUrl = "{$giteaUrl}/{$org}/{$repo}/releases/tag/{$channelTag}";
+$giteaTag = $releaseTagMap[$stability] ?? $stability;
+$channelVersion = $version . ($stabilitySuffixMap[$stability] ?? '');
+$channelDownloadUrl = "{$giteaUrl}/{$org}/{$repo}/releases/download/{$giteaTag}/{$typePrefix}{$extElement}-{$channelVersion}.zip";
+$channelInfoUrl = "{$giteaUrl}/{$org}/{$repo}/releases/tag/{$giteaTag}";

-$entries[] = buildEntry(
-	$channelName,
-	$channelVersion,
-	$channelDownloadUrl,
-	$extName,
-	$extElement,
-	$extType,
-	$clientTag,
-	$folderTag,
-	$channelInfoUrl,
-	$targetPlatform,
-	$phpTag,
-	$shaTag
-);
+for ($i = 0; $i <= $stabilityIndex; $i++) {
+	$channelName = $allChannels[$i];
+	$joomlaTag = $stabilityTagMap[$channelName] ?? $channelName;
+	// Only attach SHA to the primary channel entry
+	$entrySha = ($i === $stabilityIndex) ? $shaTag : '';
+
+	$entries[] = buildEntry(
+		$joomlaTag,
+		$channelVersion,
+		$channelDownloadUrl,
+		$extName,
+		$extElement,
+		$extType,
+		$clientTag,
+		$folderTag,
+		$channelInfoUrl,
+		$targetPlatform,
+		$phpTag,
+		$entrySha
+	);
+}

 // -- Preserve existing entries for channels not being updated -----------------
 $dest = $outputFile ?? "{$root}/updates.xml";
@@ -325,10 +334,10 @@ $preservedEntries = [];
 if (file_exists($dest)) {
 	$existingXml = @simplexml_load_file($dest);
 	if ($existingXml) {
-		// Channels we're writing — don't preserve these
+		// Joomla tags we're writing — don't preserve these
 		$writtenChannels = [];
 		for ($i = 0; $i <= $stabilityIndex; $i++) {
-			$writtenChannels[] = $allChannels[$i];
+			$writtenChannels[] = $stabilityTagMap[$allChannels[$i]] ?? $allChannels[$i];
 		}

 		foreach ($existingXml->update as $existingUpdate) {
@@ -2,7 +2,7 @@
    "name": "mokoconsulting-tech/enterprise",
    "description": "MokoStandards Enterprise API \u2014 PHP implementation",
    "type": "library",
-    "version": "07.00.00",
+    "version": "09.00.00",
    "license": "GPL-3.0-or-later",
    "authors": [
        {
@@ -92,6 +92,8 @@ class CircuitBreakerOpen extends RuntimeException
 * );
 * $response = $client->get('/repos/owner/repo');
 * ```
+ *
+ * @since 04.00.00
 */
 class ApiClient
 {
@@ -124,7 +126,6 @@ class ApiClient
    private ?DateTime $circuitLastFailure = null;

    /** @var LoggerInterface|null Optional logger instance */
-    private ?LoggerInterface $logger = null;

    /** @var array<string, mixed> Request metrics */
    private array $metrics = [
@@ -179,7 +180,6 @@ class ApiClient
        $this->circuitBreakerTimeout = $circuitBreakerTimeout;
        $this->enableCaching = $enableCaching;
        $this->userAgent = $userAgent;
-        $this->logger = $logger;
        $this->authScheme = $authScheme;

        // Initialize HTTP client
@@ -716,6 +716,9 @@ class ValidationCLI extends CLIApp
 * Lifecycle: configure() -> parseArguments() -> printBanner() -> initialize() -> run()
 *
 * All new scripts must extend CliFramework and implement configure() + run().
+ *
+ * @since   04.00.15
+ * @see     CLIApp Legacy base class (deprecated)
 */
 abstract class CliFramework
 {
@@ -932,6 +935,11 @@ abstract class CliFramework
    // Argument parsing (internal)
    // =========================================================================

+    /**
+     * Parse CLI arguments from $_SERVER['argv'] into registered argument definitions.
+     *
+     * @since 04.00.15
+     */
    private function parseArguments(): void
    {
        $argv = array_slice($_SERVER['argv'] ?? [], 1);
@@ -970,6 +978,11 @@ abstract class CliFramework
    // Help screen
    // =========================================================================

+    /**
+     * Print auto-generated help screen from registered arguments.
+     *
+     * @since 04.00.15
+     */
    protected function printHelp(): void
    {
        $w = $this->termWidth();
@@ -32,12 +32,17 @@ use RuntimeException;
 * - Workflow dir: .github/workflows
 *
 * @package MokoStandards\Enterprise
- * @version 04.06.10
+ * @since   04.06.10
+ * @see     GitPlatformAdapter
 */
 class GitHubAdapter implements GitPlatformAdapter
 {
+    /** @var ApiClient HTTP client for GitHub API calls. */
    private ApiClient $apiClient;

+    /**
+     * @param ApiClient $apiClient Configured API client for api.github.com
+     */
    public function __construct(ApiClient $apiClient)
    {
        $this->apiClient = $apiClient;
@@ -405,7 +410,7 @@ class GitHubAdapter implements GitPlatformAdapter
            $page++;
        }

-        return $all;
+        return array_values($all);
    }

    // ──────────────────────────────────────────────
@@ -175,7 +175,7 @@ interface GitPlatformAdapter
    /**
     * List all branches in a repository.
     *
-     * @return array<int, array<string, mixed>>
+     * @return array<mixed>
     */
    public function listBranches(string $org, string $repo): array;

@@ -202,7 +202,7 @@ interface GitPlatformAdapter
     * @param string $repo Repository name
     * @param string $path File path within the repository
     * @param string|null $ref Branch/tag/SHA reference (null = default branch)
-     * @return array{content: string, sha: string, size: int, encoding: string} File data (content is base64-encoded)
+     * @return array<string, mixed> File data (content is base64-encoded)
     */
    public function getFileContents(string $org, string $repo, string $path, ?string $ref = null): array;

@@ -258,7 +258,7 @@ interface GitPlatformAdapter
     * @param string $org Organization name
     * @param string $repo Repository name
     * @param array<string, mixed> $filters Filters (state, head, base, sort, direction)
-     * @return array<int, array<string, mixed>> Pull request list
+     * @return array<mixed> Pull request list
     */
    public function listPullRequests(string $org, string $repo, array $filters = []): array;

@@ -305,7 +305,7 @@ interface GitPlatformAdapter
     * @param string $org Organization name
     * @param string $repo Repository name
     * @param array<string, mixed> $filters Filters (state, labels, assignee, etc.)
-     * @return array<int, array<string, mixed>> Issue list
+     * @return array<mixed> Issue list
     */
    public function listIssues(string $org, string $repo, array $filters = []): array;

@@ -357,7 +357,7 @@ interface GitPlatformAdapter
     *
     * @param string $org Organization name
     * @param string $repo Repository name
-     * @return array<int, array{name: string, color: string, description: string}> Label list
+     * @return array<mixed> Label list
     */
    public function listLabels(string $org, string $repo): array;

@@ -406,7 +406,7 @@ interface GitPlatformAdapter
     *
     * @param string $org Organization name
     * @param string $repo Repository name
-     * @return array<int, array<string, mixed>> Protection rules
+     * @return array<mixed> Protection rules
     */
    public function listBranchProtections(string $org, string $repo): array;

@@ -445,7 +445,7 @@ interface GitPlatformAdapter
     * @param string $endpoint API endpoint path
     * @param array<string, mixed> $params Query parameters
     * @param int $perPage Items per page (platform default if 0)
-     * @return array<int, array<string, mixed>> All items across all pages
+     * @return array<mixed> All items across all pages
     */
    public function paginateAll(string $endpoint, array $params = [], int $perPage = 100): array;

@@ -34,13 +34,21 @@ use RuntimeException;
 * - Workflow dir: .mokogitea/workflows
 *
 * @package MokoStandards\Enterprise
- * @version 04.06.10
+ * @since   04.06.10
+ * @see     GitPlatformAdapter
 */
 class MokoGiteaAdapter implements GitPlatformAdapter
 {
+    /** @var ApiClient HTTP client for Gitea API calls. */
    private ApiClient $apiClient;
+
+    /** @var string Base URL for Gitea API (e.g. https://git.mokoconsulting.tech/api/v1). */
    private string $baseUrl;

+    /**
+     * @param ApiClient $apiClient Configured API client
+     * @param string    $baseUrl   Gitea API base URL
+     */
    public function __construct(ApiClient $apiClient, string $baseUrl = 'https://git.mokoconsulting.tech/api/v1')
    {
        $this->apiClient = $apiClient;
@@ -468,7 +476,7 @@ class MokoGiteaAdapter implements GitPlatformAdapter
            $page++;
        }

-        return $all;
+        return array_values($all);
    }

    // ──────────────────────────────────────────────
@@ -29,7 +29,6 @@ class RepositoryHealthChecker
 {
    private AuditLogger $logger;
    private MetricsCollector $metrics;
-    private UnifiedValidator $validator;

    private array $results = [
        'categories' => [],
@@ -50,7 +49,6 @@ class RepositoryHealthChecker
    ) {
        $this->logger = $logger ?? new AuditLogger('repo_health_checker');
        $this->metrics = $metrics ?? new MetricsCollector();
-        $this->validator = $validator ?? new UnifiedValidator();
    }

    /**
@@ -39,7 +39,6 @@ class RepositorySynchronizer
    private const VERSION_BRANCH      = 'version/' . self::STANDARDS_MAJOR;
    private const SYNC_BRANCH         = 'chore/sync-mokostandards-v' . self::STANDARDS_MINOR;

-    private ApiClient $apiClient;
    private GitPlatformAdapter $adapter;
    private AuditLogger $logger;
    private MetricsCollector $metrics;
@@ -65,7 +64,6 @@ class RepositorySynchronizer
        ?DefinitionParser $definitionParser = null,
        ?GitPlatformAdapter $adapter = null
    ) {
-        $this->apiClient        = $apiClient;
        $this->adapter          = $adapter ?? new MokoGiteaAdapter($apiClient);
        $this->logger           = $logger;
        $this->metrics          = $metrics;
@@ -1510,16 +1508,16 @@ HCL;

                    if ($updated) {
                        $results['success']++;
-                        $this->metrics->increment('repos_updated_total', ['status' => 'success']);
+                        $this->metrics->increment('repos_updated_total', 1, ['status' => 'success']);
                        $results['repositories'][$repoName] = 'updated';
                    } else {
                        $results['skipped']++;
-                        $this->metrics->increment('repos_updated_total', ['status' => 'skipped']);
+                        $this->metrics->increment('repos_updated_total', 1, ['status' => 'skipped']);
                        $results['repositories'][$repoName] = 'skipped';
                    }
                } catch (Exception $e) {
                    $results['failed']++;
-                    $this->metrics->increment('repos_updated_total', ['status' => 'failed']);
+                    $this->metrics->increment('repos_updated_total', 1, ['status' => 'failed']);
                    $results['repositories'][$repoName] = 'failed: ' . $e->getMessage();
                }

@@ -96,8 +96,6 @@ class TransactionStep
 */
 class Transaction
 {
-    private const VERSION = '04.06.00';
-
    private string $name;
    /** @var array<int, TransactionStep> */
    private array $steps = [];
@@ -6,7 +6,7 @@

 # PHPStan configuration for moko-platform projects
 parameters:
-    level: 2
+    level: 6
    paths:
        - lib
        - validate
@@ -21,3 +21,6 @@ parameters:

    checkFunctionNameCase: true
    checkInternalClassCaseSensitivity: true
+
+includes:
+    - phpstan-baseline.neon
@@ -25,7 +25,7 @@ final class CheckFileIntegrity
    private bool $verbose = false;
    private bool $jsonOutput = false;

-    /** @var array{host: string, port: int, user: string, identity: string} */
+    /** @var array<string, mixed> */
    private array $sftpConfig = [];

    public function run(): int
@@ -35,10 +35,8 @@ use MokoEnterprise\{AuditLogger, CliFramework, MetricsCollector, PluginFactory};

 class RepoHealthChecker extends CliFramework
 {
-    private const DEFAULT_THRESHOLD = 70.0;
    private AuditLogger $logger;
    private MetricsCollector $metrics;
-    private PluginFactory $pluginFactory;
    private string $apiBaseUrl = 'https://git.mokoconsulting.tech/api/v1';

    private array $results = [
@@ -61,7 +59,6 @@ class RepoHealthChecker extends CliFramework
        parent::initialize();
        $this->logger = new AuditLogger('repo_health_checker');
        $this->metrics = new MetricsCollector();
-        $this->pluginFactory = new PluginFactory($this->logger, $this->metrics);
        $config = \MokoEnterprise\Config::load();
        $this->apiBaseUrl = rtrim($config->getString('gitea.url', 'https://git.mokoconsulting.tech'), '/') . '/api/v1';
    }
@@ -38,7 +38,6 @@ class DriftScanner extends CliFramework
    private const DEFAULT_ORG = 'mokoconsulting-tech';

    private ApiClient $apiClient;
-    private AuditLogger $logger;
    private MetricsCollector $metrics;
    private \MokoEnterprise\GitPlatformAdapter $adapter;

@@ -60,7 +59,6 @@ class DriftScanner extends CliFramework
    {
        parent::initialize();

-        $this->logger = new AuditLogger('drift_scanner');
        $this->metrics = new MetricsCollector();

        // Initialize API client via platform adapter