@caddis/cli 0.4.21 → 0.4.23

package/bundles/antigravity-plugin/skills/port-to-github/scripts/Test-PortContentPolicy.ps1

@@ -0,0 +1,218 @@
+<#
+.SYNOPSIS
+  Check a staged repository against the source-only content policy, over the tips AND all history.
+
+.DESCRIPTION
+  The policy: a repository holds application code, configuration and templates, migration
+  SCRIPTS, tests, and the scripts/manifests that rebuild the environment. It does NOT hold:
+
+    runtime      a runtime or server distribution (MariaDB, PHP, JDK, Node, Python, Apache...)
+    binary       compiled or packaged files (.exe .dll .so .jar .msi, archives)
+    db-data      database data files (ibdata1, *.ibd, *.frm, *.mdf, SQLite files, dumps)
+    data-export  data files above the size threshold (.csv .xlsx .json .xml .sql ...), or any
+                 data file under a backups/dumps/exports folder
+    dependency   installed dependencies (node_modules, vendor, .venv, site-packages)
+    backup       editor and copy backups (*.bak, *.orig, *.old, *~)
+
+  Large files that match no rule are reported as 'large-review' (a decision, not a violation).
+
+  .gitignore does not remove a file that was committed before it: every excluded path is
+  checked in ALL history, not only in the current files.
+
+  Reads <staging>\<Name>\mirror.git. Changes nothing. Writes content-policy.json next to it.
+  Exit 0: compliant. Exit 1: at least one excluded path exists somewhere in history.
+
+  Project overrides (optional) in the config file, key "contentPolicy":
+    { "keep": ["regex", ...], "exclude": ["regex", ...], "dataThresholdMB": 5, "largeMB": 10 }
+  Regexes match the repository path (forward slashes).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Name,
+    [string]$StagingRoot,
+    [string]$ConfigPath,
+    [double]$DataThresholdMB,
+    [double]$LargeMB,
+    # Print every finding, not only the per-folder summary.
+    [switch]$Detail
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'PortCommon.ps1')
+
+$config = Get-PortConfig $ConfigPath
+$stage = Join-Path (Get-PortStagingRoot $config $StagingRoot) $Name
+$mirror = Join-Path $stage 'mirror.git'
+if (-not (Test-Path -LiteralPath $mirror)) { throw "No staged mirror at $mirror. Run Get-PortSource.ps1 first." }
+$manifest = Get-Content -LiteralPath (Join-Path $stage 'manifest.json') -Raw | ConvertFrom-Json
+$branch = $manifest.defaultBranch
+
+$policy = Get-PortConfigValue $config 'contentPolicy' $null
+$keepRx = @(); $extraExcludeRx = @()
+if ($policy) {
+    if ($policy.PSObject.Properties.Name -contains 'keep') { $keepRx = @($policy.keep) }
+    if ($policy.PSObject.Properties.Name -contains 'exclude') { $extraExcludeRx = @($policy.exclude) }
+    if (-not $DataThresholdMB -and $policy.PSObject.Properties.Name -contains 'dataThresholdMB') { $DataThresholdMB = [double]$policy.dataThresholdMB }
+    if (-not $LargeMB -and $policy.PSObject.Properties.Name -contains 'largeMB') { $LargeMB = [double]$policy.largeMB }
+}
+if (-not $DataThresholdMB) { $DataThresholdMB = 5 }
+if (-not $LargeMB) { $LargeMB = 10 }
+$dataBytes = [int64]($DataThresholdMB * 1MB)
+$largeBytes = [int64]($LargeMB * 1MB)
+
+# A runtime folder is the runtime's NAME, optionally followed by a version or platform tag
+# (php-8.3.33, jdk-17.0.2, node-v20.11.0-win-x64, apache24). Not any folder that merely STARTS
+# with one: redis-migrations/ or apache-poi-wrapper/ are source.
+$ver = '([-_ ]?v?\d[\w.]*(-(win|linux|x64|x86|amd64|arm64)[\w.-]*)?)?'
+$runtimeDirRx = "(?i)^(mariadb|mysql|mysql-server|php|jdk|jre|openjdk|java|python|python-embed|nodejs|node|apache|httpd|nginx|tomcat|apache-tomcat|redis|postgres|postgresql|pgsql|erlang|ruby|dotnet|go)$ver$"
+$runtimeBinRx = '(?i)^(mariadbd|mysqld|mariadb|mysql|php|php-cgi|node|python|pythonw|java|javaw|httpd|nginx|redis-server|postgres|pg_ctl|erl|ruby|dotnet)\.exe$'
+$dependencyDirRx = '(?i)^(node_modules|vendor|\.venv|venv|site-packages|bower_components|\.yarn|jspm_packages)$'
+$binaryExtRx = '(?i)\.(exe|dll|so|dylib|msi|msix|bin|iso|img|jar|war|ear|class|pyc|pdb|lib|a|o|obj|zip|7z|tar|gz|tgz|rar|bz2|xz|cab|nupkg|whl|deb|rpm)$'
+$dbDataRx = '(?i)(^|/)(ibdata\d*|ib_logfile\d*|ib_buffer_pool|aria_log[\w.]*|undo\d+)$|\.(ibd|frm|myd|myi|mdf|ldf|ndf|sqlite3?|db3|dmp)$'
+$backupRx = '(?i)(\.(bak|orig|old|swp)|~)$'
+$dataExtRx = '(?i)\.(csv|tsv|xlsx|xlsm|xlsb|xls|ods|parquet|avro|orc|jsonl|ndjson|json|xml|sql|dat|txt|log)$'
+$dataDirRx = '(?i)^(backups?|dumps?|exports?|snapshots?|data-?dumps?)$'
+
+function Get-Category([string]$Path, [int64]$Bytes) {
+    foreach ($rx in $keepRx) { if ($Path -match $rx) { return $null } }
+    foreach ($rx in $extraExcludeRx) { if ($Path -match $rx) { return 'project-exclude' } }
+    $parts = $Path -split '/'
+    $dirs = if ($parts.Count -gt 1) { $parts[0..($parts.Count - 2)] } else { @() }
+    $leaf = $parts[-1]
+    foreach ($d in $dirs) { if ($d -match $runtimeDirRx) { return 'runtime' } }
+    if ($leaf -match $runtimeBinRx) { return 'runtime' }
+    foreach ($d in $dirs) { if ($d -match $dependencyDirRx) { return 'dependency' } }
+    if ($Path -match $dbDataRx) { return 'db-data' }
+    if ($leaf -match $backupRx) { return 'backup' }
+    if ($leaf -match $binaryExtRx) { return 'binary' }
+    if ($leaf -match $dataExtRx) {
+        # Under a backups/dumps folder any data file is excluded, but a plain note (.txt/.md) is not data.
+        if ($leaf -notmatch '(?i)\.(txt|md)$') { foreach ($d in $dirs) { if ($d -match $dataDirRx) { return 'data-export' } } }
+        # Migration SCRIPTS stay by policy. A large .sql under migration(s)/ may be a script or a
+        # data load, so it is a decision, not an automatic exclusion. Data FILES there (csv, json,
+        # xlsx) are still data.
+        if ($leaf -match '(?i)\.sql$' -and ($dirs | Where-Object { $_ -match '(?i)^migrations?$' })) {
+            if ($Bytes -ge $largeBytes -or $Bytes -ge $dataBytes) { return 'large-review' }
+            return $null
+        }
+        if ($Bytes -ge $dataBytes) { return 'data-export' }
+    }
+    if ($Bytes -ge $largeBytes) { return 'large-review' }
+    return $null
+}
+
+function MGit([string[]]$a) { Invoke-PortGit (@('-C', $mirror) + $a) }
+
+# ---- every blob in history, with every path it ever had ----------------------------------
+Write-PortStep 'Reading every path and blob in history'
+$pathsBySha = @{}
+$submodules = New-Object System.Collections.Generic.HashSet[string]
+function Add-PathForSha([string]$sha, [string]$p) {
+    if (-not $pathsBySha.ContainsKey($sha)) { $pathsBySha[$sha] = New-Object System.Collections.Generic.HashSet[string] }
+    [void]$pathsBySha[$sha].Add($p)
+}
+# EVERY path a blob was ever written to. rev-list --objects names each blob only ONCE, by the
+# first path it meets, so identical content at a second path was invisible (found by the
+# dogfood: a 3-byte test image at two paths survived a clean). log --raw lists every add or
+# change, per commit, including merges (-m) and root commits.
+foreach ($l in (MGit @('-c', 'core.quotePath=false', 'log', '--all', '--raw', '--no-abbrev', '--no-renames', '-m', '--root', '--format=', '--diff-filter=AMT'))) {
+    if (-not $l -or $l[0] -ne ':') { continue }
+    $meta, $p = $l -split "`t", 2
+    $f = $meta -split ' '
+    if ($f.Count -lt 4 -or -not $p -or $f[3] -match '^0+$') { continue }
+    # Mode 160000 is a submodule: its "blob" is a commit in ANOTHER repository, invisible to a
+    # size scan. Record it, so a runtime vendored as a submodule cannot pass unnoticed.
+    if ($f[1] -eq '160000') { [void]$submodules.Add($p); continue }
+    Add-PathForSha $f[3] $p
+}
+# Safety net: anything reachable that the log did not show.
+foreach ($l in (MGit @('rev-list', '--objects', '--all'))) {
+    $sha, $p = $l -split ' ', 2
+    if ($p -and -not $pathsBySha.ContainsKey($sha)) { Add-PathForSha $sha $p }
+}
+$sizeBySha = @{}
+foreach ($l in (MGit @('cat-file', '--batch-all-objects', '--batch-check=%(objecttype) %(objectname) %(objectsize)'))) {
+    $t, $o, $s = $l -split ' '
+    if ($t -eq 'blob' -and $pathsBySha.ContainsKey($o)) { $sizeBySha[$o] = [int64]$s }
+}
+
+# Aggregate per path: largest version, number of versions.
+$byPath = @{}
+foreach ($sha in $sizeBySha.Keys) {
+    foreach ($p in $pathsBySha[$sha]) {
+        if (-not $byPath.ContainsKey($p)) { $byPath[$p] = [pscustomobject]@{ path = $p; maxBytes = [int64]0; versions = 0 } }
+        $e = $byPath[$p]; $e.versions++
+        if ($sizeBySha[$sha] -gt $e.maxBytes) { $e.maxBytes = $sizeBySha[$sha] }
+    }
+}
+
+$tipFiles = @{}
+foreach ($l in (MGit @('-c', 'core.quotePath=false', 'ls-tree', '-r', '--name-only', $branch))) { $tipFiles[$l] = $true }
+
+# ---- classify ----------------------------------------------------------------------------------
+$findings = New-Object System.Collections.Generic.List[object]
+foreach ($e in $byPath.Values) {
+    $cat = Get-Category $e.path $e.maxBytes
+    if (-not $cat) { continue }
+    $findings.Add([pscustomobject]@{
+            path = $e.path; category = $cat; maxBytes = $e.maxBytes; versions = $e.versions
+            inDefaultBranch = [bool]$tipFiles[$e.path]
+            action = if ($cat -eq 'large-review') { 'review' } else { 'exclude' }
+        })
+}
+foreach ($sm in $submodules) {
+    $findings.Add([pscustomobject]@{ path = $sm; category = 'submodule'; maxBytes = [int64]0; versions = 1; inDefaultBranch = [bool]$tipFiles[$sm]; action = 'review' })
+}
+$exclude = @($findings | Where-Object { $_.action -eq 'exclude' })
+$review = @($findings | Where-Object { $_.action -eq 'review' })
+
+# Group by top two path segments so a 3,000-file vendored runtime reads as one line.
+# Group by folder, at most 4 levels deep, so one vendored runtime reads as one line and a
+# data folder deep in an app is still named precisely.
+function Get-Group([string]$p) { $s = $p -split '/'; if ($s.Count -le 1) { return $p }; $d = $s[0..([math]::Min(3, $s.Count - 2))]; ($d -join '/') + '/' }
+$groups = @($findings | Group-Object { "$($_.category)|$(Get-Group $_.path)" } | ForEach-Object {
+        $cat, $grp = $_.Name -split '\|', 2
+        [pscustomobject]@{
+            category = $cat; group = $grp; files = $_.Count
+            historyMB = [math]::Round((($_.Group | Measure-Object maxBytes -Sum).Sum) / 1MB, 1)
+            inDefaultBranch = @($_.Group | Where-Object { $_.inDefaultBranch }).Count
+        }
+    } | Sort-Object historyMB -Descending)
+
+$totalBytes = [int64]0; foreach ($v in $sizeBySha.Values) { $totalBytes += $v }
+# Count each blob once, even when it sits at several excluded paths (a per-path sum can exceed
+# the whole history). Plain loops: Measure-Object on NO input has no .Sum under strict mode.
+$exPaths = New-Object System.Collections.Generic.HashSet[string]
+foreach ($x in $exclude) { [void]$exPaths.Add($x.path) }
+$exBytes = [int64]0
+foreach ($sha in $sizeBySha.Keys) { foreach ($p in $pathsBySha[$sha]) { if ($exPaths.Contains($p)) { $exBytes += $sizeBySha[$sha]; break } } }
+$report = [ordered]@{
+    name = $Name; defaultBranch = $branch; checkedAt = (Get-Date).ToString('o')
+    thresholds = [ordered]@{ dataThresholdMB = $DataThresholdMB; largeMB = $LargeMB }
+    historyBlobMB = [math]::Round($totalBytes / 1MB, 1)
+    excludedPaths = $exclude.Count; excludedMB = [math]::Round($exBytes / 1MB, 1)
+    reviewPaths = $review.Count
+    compliant = ($exclude.Count -eq 0)
+    groups = $groups
+    findings = @($findings | Sort-Object maxBytes -Descending)
+}
+ConvertTo-PortJsonFile $report (Join-Path $stage 'content-policy.json')
+# Plain path list, one per line, for Invoke-PortHistoryClean.ps1 and for .gitignore review.
+Set-Content -LiteralPath (Join-Path $stage 'content-policy-exclude.txt') -Value @($exclude | Sort-Object path | ForEach-Object { $_.path }) -Encoding UTF8
+
+Write-Host ''
+Write-Host ("Content policy for {0}: {1} excluded path(s), {2} MB of history; {3} path(s) to review. History holds {4} MB of blobs in total." -f $Name, $exclude.Count, $report.excludedMB, $review.Count, $report.historyBlobMB)
+if ($groups.Count -gt 0) {
+    Write-Host ''
+    Write-Host ('{0,-13} {1,-55} {2,7} {3,10} {4}' -f 'category', 'where', 'files', 'MB', 'in default branch')
+    foreach ($g in $groups) { Write-Host ('{0,-13} {1,-55} {2,7} {3,10} {4}' -f $g.category, $g.group, $g.files, $g.historyMB, $g.inDefaultBranch) }
+}
+if ($Detail) { $findings | Sort-Object maxBytes -Descending | ForEach-Object { Write-Host ('  {0,-13} {1,9:N0} KB  {2}' -f $_.category, ($_.maxBytes / 1KB), $_.path) } }
+Write-Host "    report: $(Join-Path $stage 'content-policy.json')"
+Write-Host "    exclude list: $(Join-Path $stage 'content-policy-exclude.txt')"
+if ($exclude.Count -gt 0) {
+    Write-PortWarn 'Not compliant. Decide per group: keep (add a "keep" regex to contentPolicy), or remove from history with Invoke-PortHistoryClean.ps1. Adding a path to .gitignore does NOT remove it from history.'
+    exit 1
+}
+Write-PortOk 'Compliant: no excluded content anywhere in history.'
+exit 0

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.32",
+  "version": "1.3.33",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/hld/references/gold-standard-hld.md

@@ -11,23 +11,32 @@ Last Updated: 2026-09-19T14:05:00Z
 Last Model Used: gemini-3.8-flash
 ---
 
+<!--
+GOLD STANDARD for the hld skill. Match its structure, heading numbering, diagram types and
+styling, ID schemes (SYS_nn, INT_nn, REQ-nn) and table columns exactly.
+ACCOUNTS_PER_RUN, BATCH_HOST, PDF_TOTAL and SECONDARY_SCHEDULES stand in for real, measured
+figures and names in the source HLD; they are withheld here only. A generated HLD must state
+the REAL number or name in every such place - never a placeholder, never a vague 'many'.
+Exact figures are what make the SLA and parity claims checkable.
+-->
+
 # High-Level Architecture (HLA): BriteBill Replacement Platform
 
 ## 1. Executive Summary
 
 ### 1.1 Initiative Goal
-The BriteBill Replacement Platform replaces the proprietary third-party BriteBill invoice composition system used for Virgin Media Ireland fixed billing. 
+The BriteBill Replacement Platform replaces the proprietary third-party BriteBill invoice composition system used for fixed-line customer billing. 
 
 This platform achieves the following primary business goals:
 - It eliminates third-party licensing costs, proprietary dependencies, and vendor software lock-in.
 - It provides a locally controlled, deterministic, and auditable composition engine.
 - It delivers high-throughput batch generation for four recurring monthly billing cycles: `BR-07`, `BR-14`, `BR-21`, and `BR-28`.
-- It processes approximately 124,000 customer accounts per billing run within a four-hour service level agreement (SLA) window.
+- It processes approximately `<ACCOUNTS_PER_RUN>` customer accounts per billing run within a four-hour service level agreement (SLA) window.
 - It simultaneously produces four synchronized output channels from a single canonical document model: Customer PDF, Print Spool AFP, Mailroom Index JRN, and Digital Portal XML.
 - It guarantees full financial integrity through mandatory, fail-closed automated reconciliation gates.
 
 ### 1.2 Solution Architecture Summary
-The solution operates as a standalone Python-based batch processing engine deployed on host `iegbcoppoc02`. It processes raw Kenan billing stream files (`.EN`), executes financial reconciliation, and renders customer-facing outputs. The engine isolates every run in an immutable staging directory, verifies cryptographic checksums, and publishes outputs atomically only after all financial and population gates pass.
+The solution operates as a standalone Python-based batch processing engine deployed on the dedicated batch host `<BATCH_HOST>`. It processes raw Kenan billing stream files (`.EN`), executes financial reconciliation, and renders customer-facing outputs. The engine isolates every run in an immutable staging directory, verifies cryptographic checksums, and publishes outputs atomically only after all financial and population gates pass.
 
 ### 1.3 Business Value & Operational Outcomes
 - **Cost Reduction**: Complete decommissioning of third-party composition licenses.
@@ -40,7 +49,7 @@ The solution operates as a standalone Python-based batch processing engine deplo
 ## 2. Project Context and Scope
 
 ### 2.1 Background
-Virgin Media Ireland fixed customer billing produces monthly invoices across four staggered billing cycles. The legacy composition workflow relied on an external vendor system (BriteBill). This introduced high annual licensing costs and operational delays whenever regulatory or template changes occurred. The BriteBill Replacement Platform moves invoice composition entirely onto internal infrastructure using high-performance open standards.
+Fixed-line customer billing produces monthly invoices across four staggered billing cycles. The legacy composition workflow relied on an external vendor system (BriteBill). This introduced high annual licensing costs and operational delays whenever regulatory or template changes occurred. The BriteBill Replacement Platform moves invoice composition entirely onto internal infrastructure using high-performance open standards.
 
 ### 2.2 Scope
 
@@ -65,7 +74,7 @@ Virgin Media Ireland fixed customer billing produces monthly invoices across fou
 
 ### 2.3 Architecture Boundaries and Key Assumptions
 - **Deterministic Processing**: All calculations and document renderings produce identical, byte-reproducible outputs for identical inputs.
-- **Local Filesystem Isolation**: Network-isolated execution on `iegbcoppoc02` with zero runtime external API or HTTP dependencies.
+- **Local Filesystem Isolation**: Network-isolated execution on `<BATCH_HOST>` with zero runtime external API or HTTP dependencies.
 - **Fail-Closed Operations**: Any financial discrepancy, unmapped record, or population count mismatch immediately halts the run and prevents output release.
 
 ---
@@ -168,7 +177,7 @@ sequenceDiagram
     Render->>Storage: Write outputs into staging directories
 
     Note over Orch,Targets: Stage 5: Population Audit & Atomic Release
-    Orch->>Audit: Verify population counts (PDF == XML == AFP == 124,024)
+    Orch->>Audit: Verify population counts (PDF == XML == AFP == ACCOUNTS_PER_RUN)
     Orch->>Audit: Seal freeze-manifest.json and compute final SHA-256 digests
     Orch->>Audit: Transition to RunLifecycle::READY_FOR_RELEASE
     Orch->>Targets: Copy verified artifacts to delivery endpoints
@@ -195,7 +204,7 @@ flowchart TD
         SYS_01["SYS_01: Kenan Billing Engine<br/>Rating & Billing Lifecycle"]:::existingStyle
     end
 
-    subgraph CorePlatform["BriteBill Replacement Platform (iegbcoppoc02)"]
+    subgraph CorePlatform["BriteBill Replacement Platform (BATCH_HOST)"]
         direction LR
         SYS_02["SYS_02: BriteBill Replacement Engine<br/>Ingestion, Mapping, Reconcile & Render"]:::newStyle
         SYS_06["SYS_06: Operations Control Centre<br/>Audit Journal, Sealed Manifest & CLI"]:::newStyle
@@ -204,7 +213,7 @@ flowchart TD
     subgraph Downstream["Downstream Distribution Channels"]
         direction LR
         SYS_03["SYS_03: Print House & Mailroom<br/>Physical Print & Insertion Spool"]:::existingStyle
-        SYS_04["SYS_04: My Virgin Media Portal<br/>Online eBilling XML Viewer"]:::existingStyle
+        SYS_04["SYS_04: Customer Self-Service Portal<br/>Online eBilling XML Viewer"]:::existingStyle
         SYS_05["SYS_05: Enterprise Document Archive<br/>Customer PDF Storage & Email"]:::existingStyle
     end
 
@@ -225,7 +234,7 @@ The table below catalogs all systems and platforms within the solution boundary:
 | `SYS_01` | Kenan Billing Engine (Amdocs) | Billing / Rating | Upstream rating engine producing periodic `.EN` billing stream files. | No |
 | `SYS_02` | BriteBill Replacement Composition Engine | Batch Engine | Core batch orchestration, mapping, financial reconciliation, and multi-channel rendering engine. | Yes |
 | `SYS_03` | External Print House & Mailroom Spool | Print Production | Commercial printing facility ingesting MO:DCA AFP spools and JRN insertion records. | No |
-| `SYS_04` | My Virgin Media Digital Self-Service Portal | Web Portal | Customer billing portal ingesting structured eBilling XML for web presentation. | No |
+| `SYS_04` | Customer Digital Self-Service Portal | Web Portal | Customer billing portal ingesting structured eBilling XML for web presentation. | No |
 | `SYS_05` | Enterprise Document Archive & Dispatcher | Document Repository | Long-term customer communications repository and email dispatcher ingesting certified PDF invoices. | No |
 | `SYS_06` | Operations Control Centre & Audit Journal | Ops & Governance | Operational monitoring CLI, telemetry aggregator, and sealed run manifest validator. | Yes |
 
@@ -238,7 +247,7 @@ The core processing component implemented in Python. It executes local staging,
 #### 4.2.3 SYS_03: External Print House & Mailroom Spool
 Receives binary MO:DCA AFP print spools and JRN insertion index files for postal sorting, physical paper printing, envelope inserting, and mail dispatch.
 
-#### 4.2.4 SYS_04: My Virgin Media Digital Self-Service Portal
+#### 4.2.4 SYS_04: Customer Digital Self-Service Portal
 The customer-facing digital web application that parses structured XML invoice streams to present interactive online bill breakdowns.
 
 #### 4.2.5 SYS_05: Enterprise Document Archive & Dispatcher
@@ -273,7 +282,7 @@ Delivers ASCII index files specifying sheet counts, account identifiers, envelop
 Transfers schema-validated XML documents containing invoice data for online customer self-service viewing.
 
 #### 4.3.5 INT_05: Deterministic PDF Invoices
-Transfers byte-deterministic PDF documents containing vector Virgin Media branding, billing transaction tables, and Giro payment slips.
+Transfers byte-deterministic PDF documents containing vector brand artwork, billing transaction tables, and Giro payment slips.
 
 #### 4.3.6 INT_06: Telemetry & Sealed Manifest
 Emits structured JSONL telemetry and a cryptographic `release_manifest.json` sealing file counts, execution parameters, and SHA-256 hashes.
@@ -295,7 +304,7 @@ The platform provides administrative command-line surfaces for operations and sc
 ## 5. High-Level Data and Storage Architecture
 
 ### 5.1 Host & Working Storage Topology
-The engine executes entirely within a dedicated local filesystem hierarchy on host `iegbcoppoc02`. Every batch run is isolated by unique run and attempt identifiers:
+The engine executes entirely within a dedicated local filesystem hierarchy on the dedicated batch host `<BATCH_HOST>`. Every batch run is isolated by unique run and attempt identifiers:
 
 ```
 <working_root>/<run_id>/<attempt_id>/
@@ -356,8 +365,8 @@ classDiagram
 
 ### 5.3 Multi-Channel Output Volume & Specifications
 Production metrics established during candidate certification (ATT-006 baseline):
-- **PDF Documents**: 124,980 total PDF files (124,024 primary invoices + 956 secondary itemized schedules).
-- **XML Documents**: 124,024 structured customer eBilling files.
+- **PDF Documents**: `<PDF_TOTAL>` total PDF files (`<ACCOUNTS_PER_RUN>` primary invoices + `<SECONDARY_SCHEDULES>` secondary itemized schedules).
+- **XML Documents**: `<ACCOUNTS_PER_RUN>` structured customer eBilling files.
 - **AFP Spools**: 32 consolidated MO:DCA print files matching the 32 upstream Kenan input batches.
 - **JRN Journals**: 32 postal index files containing 100% field parity with postal insertion machinery.
 
@@ -373,7 +382,7 @@ The platform security architecture adheres to strict controls defined in `docs/S
 
 ### 6.2 Zero Runtime Network Access
 - No module within `ingestion/`, `mapping/`, `templating/`, or `rendering/` initiates external HTTP or network requests during generation.
-- All fonts, styling assets, and configuration templates reside locally on disk on `iegbcoppoc02`.
+- All fonts, styling assets, and configuration templates reside locally on disk on `<BATCH_HOST>`.
 
 ### 6.3 Working Storage Path Isolation & Traversal Defense
 - File discovery resolves candidate paths and rejects any file whose resolved parent directory escapes the staging root.
@@ -395,7 +404,7 @@ The platform security architecture adheres to strict controls defined in `docs/S
 | `REQ-01` | Ingest Kenan `.EN` tagged-record streams | `SYS_02` (`ingestion/en_reader.py`) | Automated parser unit tests and zero-failure batch validation. |
 | `REQ-02` | Strong financial reconciliation | `SYS_02` (`reconciliation/checks.py`) | Full-population balance reconciliation gate (`reconcile()`). |
 | `REQ-03` | Byte-deterministic PDF rendering | `SYS_02` (`rendering/mupdf_renderer.py`) | SHA-256 byte-identity verification against certified baseline. |
-| `REQ-04` | Multi-channel parity (PDF/XML/AFP/JRN) | `SYS_02` (`mapping/*`, `rendering/*`) | Cross-output population count verification (`124,024` exact). |
+| `REQ-04` | Multi-channel parity (PDF/XML/AFP/JRN) | `SYS_02` (`mapping/*`, `rendering/*`) | Cross-output population count verification (`<ACCOUNTS_PER_RUN>` exact). |
 | `REQ-05` | Atomic release & staging isolation | `SYS_02` (`batch/orchestrator.py`) | Zero output visibility before `READY_FOR_RELEASE` and marker written last. |
 | `REQ-06` | Auditability & run sealing | `SYS_06` (`audit/manifest.py`) | Cryptographic `release_manifest.json` generation. |
 
@@ -414,6 +423,6 @@ The platform security architecture adheres to strict controls defined in `docs/S
 | Fail-Closed | An architectural principle where any detected inconsistency aborts processing before releasing outputs. |
 
 ### 8.2 Reference Documents
-- `\\iegbcoppoc02\G\britebill-replacement\README.md`: System operational runbook and architecture overview.
-- `\\iegbcoppoc02\G\britebill-replacement\docs\SECURITY_AND_PRIVACY.md`: Security controls and privacy safeguards.
-- `\\iegbcoppoc02\G\britebill-replacement\docs\PRODUCTION_CANDIDATE_ATT006.md`: Candidate certification report and benchmark results.
+- `britebill-replacement/README.md`: System operational runbook and architecture overview.
+- `britebill-replacement/docs/SECURITY_AND_PRIVACY.md`: Security controls and privacy safeguards.
+- `britebill-replacement/docs/PRODUCTION_CANDIDATE_ATT006.md`: Candidate certification report and benchmark results.

package/bundles/codex/.codex/skills/devops/port-to-github/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: port-to-github
-description: Move (port) an app or repository to GitHub from ANY source - a Gitea/GitLab/any git server URL, a local folder, a network (UNC) share, or a folder on a remote Windows box reached over WinRM - with or without existing git history. Keeps every branch and tag, verifies by SHA, translates Gitea/Forgejo Actions CI, switches deploy checkouts to GitHub with automatic rollback, and retires the old host safely. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", or "cut the deploy over to GitHub".
+description: Move (port) an app or repository to GitHub from ANY source - a Gitea/GitLab/any git server URL, a local folder, a network (UNC) share, or a folder on a remote Windows box reached over WinRM - with or without existing git history. Keeps every branch and tag, verifies by SHA, translates Gitea/Forgejo Actions CI, enforces a source-only content policy (runtimes, binaries, data exports and dependencies stay out of the repo, over ALL history, with a runtime manifest and provisioning script so the environment is still reproducible), switches deploy checkouts to GitHub with automatic rollback, and retires the old host safely. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", "keep binaries / MariaDB / PHP out of the repo", "check the repo only holds source", or "cut the deploy over to GitHub".
 ---
 
 # port-to-github
 
 Move one app to GitHub without losing history, leaking a secret, or breaking its deploy.
 
-The work is in **six phases**. Each ends in a check that can FAIL. Do not start a phase until
+The work is in **six phases**, plus the content policy (2b). Each ends in a check that can FAIL. Do not start a phase until
 the one before it passed. Scripts are in `scripts/` next to this file. They are PowerShell 7
 (`pwsh`); the parts that run on a remote box are Windows PowerShell 5.1 compatible.
 
@@ -15,6 +15,7 @@ the one before it passed. Scripts are in `scripts/` next to this file. They are
 |---|---|---|
 | 1. Stage the source | `Get-PortSource.ps1` | No. The source is only read. |
 | 2. Readiness | `Test-PortReadiness.ps1` | No. |
+| 2b. Content policy | `Test-PortContentPolicy.ps1`, `New-PortRuntimeManifest.ps1`, `Invoke-PortHistoryClean.ps1` | No. Rewrites only the local stage. |
 | 3. Publish | `Publish-PortToGitHub.ps1` | **Yes: creates a GitHub repo and pushes.** |
 | 4. CI | `Convert-PortWorkflow.ps1`, `Test-PortWorkflowParses.ps1` | Yes: a feature branch and a PR. |
 | 5. Cutover | `Switch-CheckoutOrigin.ps1` | **Yes: changes where a deploy host pulls from.** |
@@ -64,6 +65,9 @@ Read the output. These need a decision, not a shrug:
 - **Uncommitted changes** in a source checkout are left out unless you pass
   `-IncludeUncommitted`, which puts them on a separate branch `port/uncommitted-snapshot-*`.
   The real branches stay exactly as committed. Ask the user which they want.
+- **Default branch.** From a server or a bare repository, its HEAD. From a WORKING checkout,
+  `main` (or `master`) when it exists, because the checked-out branch is only what someone had
+  open; the script says when it made that choice. Override with `-DefaultBranch <name>`.
 - **Remote-only branches**: branches the checkout only knows as `origin/x`. If the checkout is
   the only copy, re-run with `-PromoteRemoteBranches origin`. If a server has them, port from it.
 - **Likely secrets** in a plain folder or a snapshot stop the script (exit 2). Nothing has left
@@ -93,6 +97,63 @@ deploy jobs included. Readiness lists those branches; publish refuses them unles
 (the new repo will expose them), CI credentials, dependency hosts, runner labels, files that
 still name the old host. The report is in `readiness.json`.
 
+## Phase 2b - content policy: source only
+
+**The rule.** The repository holds application code, configuration and templates, migration
+SCRIPTS, tests, and the scripts and manifests that rebuild the environment. Runtime and server
+distributions (MariaDB, PHP, JDK, Node, Python, Apache...), binaries and archives, database data
+files, data exports and installed dependencies stay OUT, and are installed or provisioned
+separately. This is the default for every port; a project narrows or widens it with a
+`contentPolicy` block in its config (`keep` / `exclude` regexes, `dataThresholdMB`, `largeMB`).
+
+```powershell
+& $s/Test-PortContentPolicy.ps1 -Name <repo-name>
+```
+
+It checks the default branch AND every blob in history, because **`.gitignore` does not remove a
+file that was committed before it**. Exit 1 means excluded content exists somewhere in history.
+The output groups findings by folder; `content-policy.json` has every path.
+
+For each group, decide with the user:
+
+1. **It belongs** (a small fixture, a vendored library the team maintains) -> add a `keep` regex
+   to the project config and re-run.
+2. **It does not** -> remove it from the STAGE's history. Two ways, and it is the owner's call:
+   ```powershell
+   & $s/Invoke-PortHistoryClean.ps1 -Name <repo-name> -Mode Rewrite      # keep history, drop the paths
+   & $s/Invoke-PortHistoryClean.ps1 -Name <repo-name> -Mode FreshStart   # one commit of today's files
+   ```
+   `Rewrite` keeps every branch, tag and commit but CHANGES commit SHAs from the first affected
+   commit on; anything quoting an old SHA stops matching. `FreshStart` is smallest and drops all
+   history, other branches and tags. Both re-run the policy check and exit 1 if anything
+   excluded survived. The source keeps its original history either way.
+
+**Keep the environment reproducible.** Excluding a runtime is only safe if the repo says how to
+get it back. Scan the SOURCE FOLDER (runtimes usually live in an ignored `tools/`):
+
+```powershell
+& $s/New-PortRuntimeManifest.ps1 -Path <source-folder> [-ComputerName <box>] -OutDir <clone>\environment
+```
+
+It writes `runtimes.json` (kind, exact version, binary SHA-256, data folders), `provision.ps1`
+(downloads and unpacks each runtime with a known public source and FAILS for any it cannot
+provision), `README.md`, and `config-templates/`: configuration found inside runtime folders
+(`my.ini`, `php.ini`, `config/`, `metadata/`). Configuration is app content even when the runtime
+around it is not. Files that look like they hold a credential are withheld and listed; make
+those templates by hand with placeholders. **The credential check is a heuristic: read every
+copied template yourself before committing it.** The dogfood found one it missed (a SAML test
+user written as `'name:password' => array(...)`); the rule now covers that form, but the next
+form may be new. Nothing it finds is executed; versions come from file
+metadata. Commit `environment/` on the phase 4 branch, by file name.
+
+Two things it cannot decide, so you must:
+- **UNCLASSIFIED folders** beside a runtime (a deployed web tree, a library with no binary).
+  Decide each: provision it, rebuild it from repo code, or keep it in the repo.
+- **Data folders** (e.g. a database `data/` directory). This is state, not code. The repo carries
+  the schema and migrations; the data comes from a backup. Say where that backup lives.
+
+Then add every excluded folder to `.gitignore` on the phase 4 branch, so it cannot come back.
+
 ## Phase 3 - publish (ask first)
 
 Tell the user: the repo name, owner, visibility, branch and tag counts. Then:
@@ -101,7 +162,7 @@ Tell the user: the repo name, owner, visibility, branch and tag counts. Then:
 & $s/Publish-PortToGitHub.ps1 -Name <repo-name> [-Owner <org>] [-Visibility private]
 ```
 
-It first checks the stage still holds exactly the refs phase 1 recorded (anything else would be
+It refuses a stage whose content policy is not compliant (run phase 2b; `-AcceptContentPolicy` records an explicit owner exception instead). It then checks the stage still holds exactly the refs phase 1 recorded (anything else would be
 pushed and then "verified" against itself), creates the repo EMPTY, pushes `refs/heads/*` and
 `refs/tags/*` with an explicit refspec, sets the default branch, and compares every ref by SHA
 (exit 1 on any difference). Do not run other git commands inside the stage; if you did,

package/bundles/codex/.codex/skills/devops/port-to-github/scripts/Get-PortSource.ps1

@@ -37,6 +37,9 @@ param(
     # What to do when a plain folder or an uncommitted snapshot contains a likely secret.
     [ValidateSet('Stop', 'Exclude')][string]$OnSecret = 'Stop',
     [string]$InitialBranch = 'main',
+    # The GitHub default branch. Default: the server's HEAD; for a working checkout, main/master
+    # when present (the checked-out branch is only what someone had open).
+    [string]$DefaultBranch,
     # Replace an existing staging folder for this Name.
     [switch]$Force
 )
@@ -315,6 +318,7 @@ switch ($kind) {
                     }
                 }
                 $r.isRepo = $isRepo
+                $r.isBare = $isBare
                 if ($isRepo) {
                     $bundle = Join-Path $tmp 'repo.bundle'
                     & $git -c safe.directory=* -C $Path bundle create $bundle --all 2>&1 | Out-Null
@@ -362,7 +366,13 @@ switch ($kind) {
                 Invoke-PortGit @('bundle', 'verify', $localBundle) | Out-Null
                 Invoke-PortGit @('clone', '-q', '--mirror', $localBundle, $mirror) | Out-Null
                 $manifest.hadGitHistory = $true
-                $manifest.sourceHead = if ($remote.head) { $remote.head } else { $remote.headSha }
+                # A bare repository's HEAD is authoritative, like a server's; only a WORKING checkout's
+                # HEAD is 'whatever was open'. Leaving sourceHead empty keeps the main-line preference off.
+                $manifest.sourceHead = if ($remote.isBare) { $null } elseif ($remote.head) { $remote.head } else { $remote.headSha }
+                # A bundle records HEAD as a commit, not a branch name, so a clone of it GUESSES the
+                # default when two branches share that commit. For a bare repo the name read on the
+                # far side is authoritative; carry it across.
+                if ($remote.isBare -and $remote.head) { $authHead = $remote.head }
                 $manifest.dirtyFiles = @($remote.dirty)
                 if ($manifest.dirtyFiles.Count -gt 0) {
                     if ($IncludeUncommitted -and $remote.dirtyZip) {
@@ -430,11 +440,29 @@ if ($heads.Count -eq 0) { throw "The source produced no branches. Nothing to por
 
 $symHead = Invoke-PortGit -AllowFailure @('-C', $mirror, 'symbolic-ref', '--short', 'HEAD')
 $def = if ($symHead.ExitCode -eq 0) { $symHead.Output -join '' } else { $null }
+$mainLine = @('main', 'master') | Where-Object { $headNames -contains $_ } | Select-Object -First 1
+if (-not (Get-Variable -Name authHead -ErrorAction SilentlyContinue)) { $authHead = $null }
+# The branch the source checkout was really on (a bundle's HEAD is only a guess), so the
+# main-line choice below can say what it replaced.
+if ($manifest.sourceHead -and ($headNames -contains $manifest.sourceHead)) { $def = $manifest.sourceHead }
+if ($DefaultBranch) {
+    if (-not ($headNames -contains $DefaultBranch)) { throw "-DefaultBranch '$DefaultBranch' is not a branch in the source." }
+    $def = $DefaultBranch
+}
+elseif ($authHead -and ($headNames -contains $authHead)) {
+    $def = $authHead
+}
+elseif ($kind -ne 'url' -and $manifest.sourceHead -and $mainLine -and $def -ne $mainLine) {
+    # A server's HEAD IS its default branch. A working checkout's HEAD is only whatever branch
+    # someone had open, so prefer the main line when there is one, and say so.
+    $manifest.warnings += "The checkout was on '$def', but '$mainLine' exists, so '$mainLine' is the default branch on GitHub. Pass -DefaultBranch to choose another."
+    $def = $mainLine
+}
 if (-not $def -or -not ($headNames -contains $def)) {
     $def = @('main', 'master', 'develop') | Where-Object { $headNames -contains $_ } | Select-Object -First 1
     if (-not $def) { $def = $headNames[0] }
-    Invoke-PortGit @('-C', $mirror, 'symbolic-ref', 'HEAD', "refs/heads/$def") | Out-Null
 }
+Invoke-PortGit @('-C', $mirror, 'symbolic-ref', 'HEAD', "refs/heads/$def") | Out-Null
 $manifest.defaultBranch = $def
 
 if ($manifest.remoteOnlyBranches.Count -gt 0) {