universal-dev-standards 5.12.1 → 5.13.2

package/bundled/ai/standards/deployment-standards.ai.yaml

@@ -12,11 +12,14 @@ standard:
     - "Automate build, test, deploy, and rollback"
 
   meta:
-    version: "1.1.0"
-    updated: "2026-05-13"
+    version: "1.2.0"
+    updated: "2026-05-26"
     source: core/deployment-standards.md
     description: >
       Safe deployment strategies, feature flags, rollback, environment parity, and DORA metrics.
+      v1.2.0: Added Defensive Deployment Ordering — required extract-verify-then-delete sequence,
+      PowerShell + bash verify snippets, failure mode mapping, cross-link to packaging-standards
+      Archive Format Integrity (XSPEC-231 / closes issue #110).
       v1.1.0: Added environment stratification responsibility matrix and stub server CI/CD
       lifecycle rules (XSPEC-204).
 
@@ -230,6 +233,51 @@ stub_server_cicd_rules:
     (a) fully testable in UAT via real service or Level 2 stub server, OR
     (b) explicitly documented as PRD-smoke-only with a smoke test plan.
 
+defensive_ordering:
+  scope: "destructive-update deploy patterns (stop → swap → start) common to Windows IIS, SystemD-managed services, and similar in-place replacement workflows."
+  forbidden_ordering: |
+    1. Stop service
+    2. Extract new package         ← may silently no-op on format mismatch
+    3. Delete old install          ← runs unconditionally — destroys live install
+    4. Copy new install            ← throws (source doesn't exist)
+    5. Start service               ← cannot start (binaries gone)
+  required_ordering: |
+    1. Stop service
+    2. Extract new package → staging area  (NOT directly over live install)
+    3. ✅ VERIFY staging area contains expected artifacts
+       ↑ if verification fails: abort, do NOT touch the live install
+    4. Backup live install                 (or earlier — both is fine)
+    5. Delete old install (preserving logs / runtime data)
+    6. Copy new install from staging
+    7. Restore preserved configs
+    8. Start service
+    9. Sanity check (HTTP probe / health endpoint)
+  verify_step_3:
+    required: true
+    skip_allowed: false
+    minimum: "Test-Path / [ -f ... ] against at least one well-known file from the new package."
+    preferred: "Hash-check a manifest of expected files."
+  rules:
+    - id: extract-to-staging-not-live
+      requirement: "Step 2 MUST extract to a staging area separate from the live install path."
+      priority: required
+    - id: verify-before-destructive
+      requirement: "Step 3 MUST verify staging contents before any destructive step touches the live install. Failure MUST abort with live install untouched."
+      priority: required
+    - id: backup-required
+      requirement: "A backup of the live install MUST exist before step 5 (delete). Can be taken earlier."
+      priority: required
+    - id: preserve-runtime-data
+      requirement: "Step 5 MUST exclude logs and runtime data from deletion."
+      priority: required
+  failure_modes_addressed:
+    - wrong_format_archive: "Step 3 verify fails — live install untouched"
+    - partial_extract: "Step 3 verify fails — live install untouched"
+    - archive_root_changed: "Step 3 verify fails — live install untouched"
+    - permission_denied_extract: "Step 3 verify fails — live install untouched"
+  upstream_prevention: "Producer-side prevention via packaging-standards Archive Format Integrity. Both layers form defense-in-depth — neither alone is sufficient."
+  failure_mode_reference: "PROD incident 2026-05-24: Expand-Archive silent no-op on tar-renamed-to-.zip + unconditional Remove-Item destroyed live install. ~3 minutes downtime. Step 3 verify would have aborted before destruction."
+
 physical_spec:
   type: custom_script
   validator:

package/bundled/ai/standards/logging.ai.yaml

@@ -3,10 +3,10 @@
 
 id: logging
 meta:
-  version: "1.2.0"
-  updated: "2026-03-18"
+  version: "1.3.0"
+  updated: "2026-05-26"
   source: core/logging-standards.md
-  description: Logging levels, structured logging, and best practices
+  description: Logging levels, structured logging, file rotation policy, and best practices
 
 log_levels:
   ordered:
@@ -119,6 +119,43 @@ rules:
       Correlate all three via trace_id/span_id
     priority: recommended
 
+  - id: rotation-dual-trigger
+    trigger: configuring file-based log sink
+    instruction: |
+      File-based log sinks MUST set both rotation triggers:
+        1. Time-based: rollingInterval=Day (or equivalent)
+        2. Size-based: fileSizeLimitBytes explicit AND rollOnFileSizeLimit=true
+      Default size caps are hostile in production — Serilog silently drops at 1 GB
+      if rollOnFileSizeLimit is left at default false; log4j / Winston / Python
+      RotatingFileHandler likewise drop or grow unbounded without explicit config.
+      Recommended starting value: fileSizeLimitBytes=104857600 (100 MB),
+      retainedFileCountLimit >= N*7 where N = max expected rolls per day.
+    priority: required
+
+  - id: rotation-ops-sop
+    trigger: log file size approaching cap
+    instruction: |
+      If a log file size reaches >= 90% of fileSizeLimitBytes at expected end-of-day,
+      INVESTIGATE the cause (noisy retry loop, unbounded debug logging, stack-trace
+      flood) BEFORE raising the cap. Raising the cap masks the noise problem.
+    priority: required
+
+rotation_policy:
+  must_set_both:
+    time_based: rollingInterval=Day (or equivalent)
+    size_based:
+      fileSizeLimitBytes: explicit (100 MB recommended)
+      rollOnFileSizeLimit: true
+  hostile_defaults:
+    serilog: silently stops at 1 GB if rollOnFileSizeLimit=false
+    log4j: drops if no SizeBasedTriggeringPolicy
+    python_rotatingfilehandler: grows unbounded if maxBytes unset
+    winston: drops if maxSize unset
+  recommended:
+    fileSizeLimitBytes: 104857600
+    retainedFileCountLimit_formula: "N * 7 (N = max rolls/day)"
+  ops_sop: investigate noise root cause at >= 90% size before raising cap
+
 quick_reference:
   level_selection:
     columns: [Question, Level]

package/bundled/ai/standards/packaging-standards.ai.yaml

@@ -12,8 +12,8 @@ standard:
     - "Pipeline-integrated: packaging runs between Review and Deploy in the adoption-layer pipeline"
 
   meta:
-    version: "1.0.0"
-    updated: "2026-04-15"
+    version: "1.1.0"
+    updated: "2026-05-26"
     source: core/packaging-standards.md
 
   principles:
@@ -135,6 +135,29 @@ recipe_selection_guide:
               yes: windows-installer
               no: custom-recipe-required
 
+archive_format_integrity:
+  rules:
+    - id: real_format_matches_extension
+      requirement: "A .zip file MUST be a real ZIP archive (PKZip magic PK\\x03\\x04). A renamed POSIX tar with .zip extension is forbidden."
+      priority: required
+    - id: verify_before_publish
+      requirement: "Packaging step MUST verify the produced archive's real format before declaring success."
+      priority: required
+      verification_examples:
+        zip_python: "python -c \"import zipfile; zipfile.ZipFile('out.zip').namelist()\""
+        zip_unix: "file out.zip  # expect 'Zip archive data', NOT 'POSIX tar archive'"
+        targz_unix: "tar -tzf out.tar.gz >/dev/null"
+    - id: windows_recipe_compliance
+      requirement: "On Windows, use PowerShell Compress-Archive or .NET ZipFile::CreateFromDirectory. Do NOT use git-bash 'tar -a -cf x.zip' — the auto-extension flag produces a POSIX tar archive."
+      priority: required
+      do_use:
+        - "Compress-Archive -Path 'publish\\*' -DestinationPath 'dist\\patch.zip' -Force"
+        - "[System.IO.Compression.ZipFile]::CreateFromDirectory(...)"
+      do_not_use:
+        - "tar -a -cf x.zip ...  # produces POSIX tar with .zip extension on Windows tar ports"
+  consumer_side_defense: "Producers cannot guarantee verification downstream. Deploy scripts MUST verify archive integrity before any destructive action — see deployment-standards Defensive Deployment Ordering."
+  failure_mode_reference: "PROD incident 2026-05-24: tar-renamed-to-.zip + Expand-Archive silent no-op + unconditional Remove-Item destroyed live install. ~3 minutes downtime."
+
 physical_spec:
   type: custom_script
   validator:

package/bundled/ai/standards/self-review-protocol.ai.yaml

@@ -0,0 +1,144 @@
+# Self-Review Protocol - AI Optimized
+# Source: core/self-review-protocol.md
+
+id: self-review-protocol
+meta:
+  version: "1.0.0"
+  updated: "2026-05-26"
+  source: core/self-review-protocol.md
+  description: Mandatory self-review pass on large markdown edits before commit; catches 6 categories of internal cross-reference inconsistencies that internal reasoning routinely misses
+
+trigger_conditions:
+  mandatory:
+    condition: commit modifies > 50 lines of markdown
+    artefact_types:
+      - ADR (architecture decision records, DEC-NNN)
+      - XSPEC (cross-project specs)
+      - XSPEC SDD Deltas
+      - SKILL.md (Claude Code custom skills)
+      - ARCHITECTURE.md
+      - API.md
+      - DEPLOYMENT.md
+      - MIGRATION.md
+      - runbooks
+      - playbooks
+      - README.md (when modifying major sections)
+  optional:
+    condition: commit modifies <= 50 lines of markdown
+    rationale: small edits rarely have cross-reference risk
+  not_applicable:
+    condition: code or config only changes
+    rationale: covered by lint, test, and code review
+
+inconsistency_categories:
+  - id: 1
+    name: diagram_step_mismatch
+    description: Diagram or flow chart out of sync with step list
+    example: workflow diagram has 7 boxes but document defines 8 steps
+    check: count diagram nodes vs `## Step N:` / `## N.` headers
+  - id: 2
+    name: changelog_reference_error
+    description: Changelog entry references wrong anchor
+    example: changelog says "Step 1 added X" but X actually at Step 0
+    check: for each changelog line, grep the anchor it references
+  - id: 3
+    name: count_drift
+    description: Explicit number in text out of sync with actual count
+    example: "self-audit has 4 questions" but list has 7
+    check: grep for "N questions", "N rows", "N items" and verify
+  - id: 4
+    name: stale_template
+    description: Hardcoded model names, tool versions, dates not updated
+    example: commit template hardcodes Claude Sonnet 4.6 when model varies
+    check: find hardcoded specifics; replace with placeholders or update
+  - id: 5
+    name: wrong_tool_reference
+    description: Recommended CLI command does not do what described
+    example: recommends `claude --version` for model name (shows CLI version)
+    check: for each CLI command mentioned, mental check or `--help` verify
+  - id: 6
+    name: placeholder_rule_misalignment
+    description: Example contradicts current rule or latest case experience
+    example: example shows D1/D2/D3 but rule says D3 not mandatory
+    check: every concrete value in examples consistent with current rules
+
+procedure:
+  step_1:
+    name: re_read_full_file
+    description: Use file-reading tool to read entire file (not just diff)
+    when: after editing, before committing
+  step_2:
+    name: walk_categories
+    description: Apply 6 categories above against the file
+  step_3:
+    name: fix_in_same_commit
+    description: If issues found, edit in place and include fixes in same commit
+    rationale: ship-and-patch creates follow-up commits; in-place fix is cleaner
+  step_4:
+    name: patch_if_already_committed
+    description: If issues found after commit, create patch commit (e.g., v1.2.1 fixes v1.2.0)
+
+recording_formats:
+  skill_md:
+    location: changelog line in frontmatter or near top
+    format: '> **v{X.Y.(Z+1)} Self-review pass {YYYY-MM-DD}**: {N} issues found, {M} fixed in same commit'
+  adr_dec:
+    location: '## Follow-up Tracking table'
+    format: '| Self-review pass | This DEC | ✅ YYYY-MM-DD (6 categories, no issues) |'
+  xspec_sdd_delta:
+    location: after non-modification list section (e.g. §N.6)
+    format: '> Self-review pass: YYYY-MM-DD (6 categories, no issues)'
+  commit_message_body:
+    location: last line of commit body
+    format: 'Self-review (protocol v1.0.0): N issues found, M applied in same commit / 0 found.'
+
+distinction_from_other_practices:
+  code_review:
+    covers: code correctness, design, security
+    trigger: before merging code PR
+    source_standard: code-review.md
+  content_self_audit:
+    covers: content completeness (all required sections present)
+    trigger: each artefact creation
+    example: eval-source skill 7-question audit
+  self_review_protocol:
+    covers: internal cross-reference consistency (form, not content)
+    trigger: after large markdown edit, before commit
+    source_standard: self-review-protocol.md (this standard)
+  peer_review:
+    covers: independent perspective, blast radius assessment
+    trigger: significant changes
+
+anti_patterns:
+  - skipping_because_diff_small:
+      problem: small diffs in large files often introduce cross-ref errors elsewhere
+      mitigation: trigger is whole-file size, not diff size
+  - reviewing_diff_only:
+      problem: cross-ref errors may live in unchanged sections referencing changed content
+      mitigation: re-read whole file, not just diff
+  - document_without_practice:
+      problem: discipline is in the practice, not the documentation
+      mitigation: enforce in commit checklist
+  - substitute_for_peer_review:
+      problem: self-review catches inconsistencies, not design flaws
+      mitigation: keep peer review for significant changes
+
+verification:
+  metrics:
+    - patch_commit_ratio:
+        description: ratio of v1.X.0 -> v1.X.1 follow-up patches for same artefact
+        target: significant drop after adopting; eval-source went from 100% to 0% after v1.3.0
+    - issue_surface_time:
+        description: issues caught by self-review (pre-commit) vs by next reader (post-commit)
+        target: pre-commit grows, post-commit shrinks
+
+examples_in_the_wild:
+  - artefact: dev-platform/.claude/skills/eval-source/SKILL.md
+    version: v1.3.0
+    commit: 6b45c5d
+    note: first SKILL.md edit to pass self-review pre-commit; preceded by 2 patch cycles (v1.1.0->v1.1.1 with 3 issues, v1.2.0->v1.2.1 with 6 issues) that motivated this standard
+
+self_review:
+  date: "2026-05-26"
+  issues_found: 0
+  notes: First draft self-review pass; no internal inconsistencies detected

package/bundled/core/deployment-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/deployment-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-02-09
+**Version**: 1.1.0
+**Last Updated**: 2026-05-26
 **Applicability**: All software projects with deployment pipelines
 **Scope**: universal
 **Industry Standards**: Twelve-Factor App, Google SRE — Release Engineering, DORA State of DevOps
@@ -219,6 +219,103 @@ Strategies are not mutually exclusive. Common combinations:
 
 ---
 
+## Defensive Deployment Ordering
+
+When a deploy script replaces a running install (the destructive-update pattern common to Windows IIS, SystemD-managed services, or any "stop → swap → start" workflow), the ordering of destructive steps relative to verification is non-negotiable.
+
+### The forbidden ordering
+
+```
+1. Stop service
+2. Extract new package         ← may silently no-op on format mismatch
+3. Delete old install          ← runs unconditionally — destroys the running install
+4. Copy new install            ← throws (source doesn't exist)
+5. Start service               ← cannot start (binaries gone)
+```
+
+If step 2 silently fails (corrupt archive, wrong format, disk full, permissions), step 3 still runs and **destroys the running install**, leaving nothing to recover from except backup. Backup helps for full rollback but does NOT prevent the outage window — the service is already down.
+
+### The required ordering — extract, verify, then delete
+
+The destructive deploy ordering **MUST** be:
+
+```
+1. Stop service
+2. Extract new package → staging area      (NOT directly over live install)
+3. ✅ VERIFY staging area contains expected artifacts
+   ↑ if verification fails: abort, do NOT touch the live install
+4. Backup live install                     (or done earlier — both is fine)
+5. Delete old install (preserving logs / runtime data)
+6. Copy new install from staging
+7. Restore preserved configs
+8. Start service
+9. Sanity check (HTTP probe / health endpoint)
+```
+
+**Step 3 verification is non-negotiable.** Minimum verification is checking that at least one well-known file from the new package exists in the staging area. Hash-checking a manifest of expected files is preferred when available.
+
+### Verification snippets
+
+**PowerShell** (Windows IIS deploy):
+
+```powershell
+$staging = "C:\deploy\staging-$(Get-Date -Format yyyyMMddHHmmss)"
+Expand-Archive -Path $zipPath -DestinationPath $staging -Force
+
+# Non-negotiable: verify staging before touching live install
+if (-not (Test-Path "$staging\api\MyApp.dll")) {
+    throw "Expected $staging\api\MyApp.dll not found — archive may be corrupt or wrong format. Aborting deploy. Live install untouched."
+}
+
+# Only NOW touch live install
+Copy-Item "$apiDir" "$backupDir" -Recurse -Force
+Get-ChildItem $apiDir -Exclude logs | Remove-Item -Recurse -Force
+Copy-Item "$staging\api\*" $apiDir -Recurse
+```
+
+**bash** (Linux SystemD-managed service):
+
+```bash
+set -euo pipefail
+
+STAGING="/srv/deploy/staging-$(date +%Y%m%d%H%M%S)"
+mkdir -p "$STAGING"
+tar -xzf "$ARCHIVE" -C "$STAGING"
+
+# Non-negotiable: verify staging before touching live install
+if [ ! -f "$STAGING/bin/myapp" ]; then
+  echo "ERROR: Expected $STAGING/bin/myapp not found. Aborting deploy. Live install untouched." >&2
+  exit 1
+fi
+
+# Only NOW touch live install
+systemctl stop myapp
+cp -a "$LIVE_DIR" "$BACKUP_DIR"
+find "$LIVE_DIR" -mindepth 1 -not -path "$LIVE_DIR/logs*" -delete
+cp -a "$STAGING"/* "$LIVE_DIR/"
+systemctl start myapp
+```
+
+### Failure modes addressed
+
+| Failure mode | What protects against it |
+|---|---|
+| Archive is wrong format (e.g., tar renamed to `.zip`) | Step 3 verify fails — live install untouched |
+| Partial extract (disk full mid-extract) | Step 3 verify fails — live install untouched |
+| Archive root structure changed (extra wrapper folder, missing key file) | Step 3 verify fails — live install untouched |
+| Permissions issue (extract step had read but not write) | Step 3 verify fails — live install untouched |
+| Backup script itself fails | Optional secondary check after step 4 |
+
+### Upstream prevention
+
+Verifying at the consumer side is the last line of defense. The **upstream** prevention — refusing to produce a misformatted archive in the first place — is covered by [Packaging Standards — Archive Format Integrity](packaging-standards.md#archive-format-integrity). Both layers together form a defense-in-depth pair; neither alone is sufficient.
+
+### Failure mode reference (real incident)
+
+A Windows IIS production deploy script (2026-05-24) ran `Expand-Archive` against a tar-renamed-to-`.zip` archive (silent no-op), then `Remove-Item -Recurse` against the live `apiDir`, then `Copy-Item` from a source that did not exist (because nothing had been extracted). The live install was wiped, AppPool stopped, production was down for ~3 minutes until backup-based rollback completed. Adding step 3 verify (`Test-Path "$staging/api/MyApp.dll"`) would have aborted the deploy at the staging stage with the live install untouched.
+
+---
+
 ## Post-Deployment Checklist
 
 ### Immediate (< 5 minutes)
@@ -334,6 +431,7 @@ Smoke test failure MUST block the deployment from proceeding and trigger a rollb
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-05-26 | Added: Defensive Deployment Ordering section — required extract-verify-then-delete sequence, PowerShell + bash verify snippets, failure mode mapping, cross-link to packaging-standards Archive Format Integrity (XSPEC-231 / closes issue #110) |
 | 1.0.0 | 2026-02-09 | Initial release |
 
 ---

package/bundled/core/logging-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/logging-standards.md)
 
-**Version**: 1.2.0
-**Last Updated**: 2026-01-24
+**Version**: 1.3.0
+**Last Updated**: 2026-05-26
 **Applicability**: All software projects
 **Scope**: universal
 **Industry Standards**: RFC 5424, OpenTelemetry, W3C Trace Context
@@ -595,6 +595,117 @@ For endpoints called thousands of times per second:
 | WARN | 90 days |
 | ERROR/FATAL | 1 year |
 
+---
+
+## Log File Rotation Policy
+
+### Rotation policy — MUST set both
+
+A file-based log sink configuration **MUST** include **both** triggers:
+
+1. **Time-based rotation** (`rollingInterval: Day` or equivalent) — for chronological partitioning
+2. **Size-based rotation** with `rollOnFileSizeLimit: true` (or equivalent) — to handle volume spikes
+
+> **Why mandatory:** Most logging libraries ship with a silent default size cap. When the file hits the cap, subsequent log writes are **dropped silently** — no warning, no error. The application keeps running while half a day of logs vanish. Setting both triggers explicitly defeats this trap.
+
+### Default cap is hostile in production
+
+| Library | Default size cap | Behavior when cap hit |
+|---|---|---|
+| Serilog File sink (.NET) | 1 GB | **Silently stops writing** (`RollOnFileSizeLimit = false` by default) |
+| log4j RollingFileAppender | none unless set | Same — no roll = drops |
+| Python `RotatingFileHandler` | infinite unless `maxBytes` set | Grows unbounded |
+| Winston `winston-daily-rotate-file` | none unless `maxSize` set | Same — no roll = drops |
+
+If you do not explicitly configure size-based rotation, you are accepting one of the failure modes above.
+
+### Recommended starting values
+
+| Parameter | Value | Rationale |
+|---|---|---|
+| `fileSizeLimitBytes` | 100 MB | Balance: small enough to open in an editor, large enough to avoid excessive rolls |
+| `rollOnFileSizeLimit` | `true` | When cap hit, create `*-001.txt`, `*-002.txt`; do **NOT** drop |
+| `retainedFileCountLimit` | ≥ N×7 where N = max expected rolls/day | Avoid premature deletion of in-window logs |
+
+### Recipes per language
+
+**.NET / Serilog** (`appsettings.json`):
+
+```json
+{
+  "Serilog": {
+    "WriteTo": [{
+      "Name": "File",
+      "Args": {
+        "path": "logs/app-.txt",
+        "rollingInterval": "Day",
+        "fileSizeLimitBytes": 104857600,
+        "rollOnFileSizeLimit": true,
+        "retainedFileCountLimit": 90
+      }
+    }]
+  }
+}
+```
+
+**Python** (`logging.handlers`):
+
+```python
+from logging.handlers import RotatingFileHandler
+
+handler = RotatingFileHandler(
+    filename="logs/app.log",
+    maxBytes=104857600,   # 100 MB
+    backupCount=90        # ~3 months of rolls assuming low cardinality
+)
+# For combined time+size rotation, compose TimedRotatingFileHandler with size check
+# or use a third-party library such as concurrent-log-handler.
+```
+
+**Java / log4j2** (`log4j2.xml`):
+
+```xml
+<RollingFile name="App" fileName="logs/app.log"
+             filePattern="logs/app-%d{yyyy-MM-dd}-%i.log.gz">
+  <PatternLayout pattern="%d %-5p %c{1.} - %m%n"/>
+  <Policies>
+    <TimeBasedTriggeringPolicy interval="1"/>
+    <SizeBasedTriggeringPolicy size="100 MB"/>
+  </Policies>
+  <DefaultRolloverStrategy max="90"/>
+</RollingFile>
+```
+
+**Node / Winston** (`winston-daily-rotate-file`):
+
+```javascript
+import DailyRotateFile from "winston-daily-rotate-file";
+
+new DailyRotateFile({
+  filename: "logs/app-%DATE%.log",
+  datePattern: "YYYY-MM-DD",
+  maxSize: "100m",
+  maxFiles: "90d"
+});
+```
+
+### Operational SOP — investigate, don't just raise the cap
+
+If a log file size reaches ≥ 90% of `fileSizeLimitBytes` at expected end-of-day, **investigate the cause before raising the cap**. Typical root causes:
+
+- Noisy retry loop logging every attempt at INFO instead of WARN summary
+- Unbounded debug logging accidentally enabled in production
+- Stack-trace flood from one upstream failure
+- Health probe / sidecar polluting the business log
+
+Raising the cap masks the underlying noise problem and pushes the next outage further out.
+
+### Failure-mode reference (real incident)
+
+A production .NET Worker using only `rollingInterval: Day` (no size limit set, Serilog default 1 GB cap) hit the cap at 07:31 and silently dropped every log entry until 13:00+ when the operator noticed the tail was stale. Five consecutive daily files showed `~1,073,741,8XX bytes` (= 1 GiB exactly, Serilog default). Half a day of production diagnostics were lost. Setting `fileSizeLimitBytes` + `rollOnFileSizeLimit: true` would have rolled to `worker-YYYYMMDD_001.txt` and preserved the events.
+
+---
+
 ## Quick Reference Card
 
 ### Log Level Selection
@@ -623,6 +734,14 @@ App cannot continue?         → FATAL
 - [ ] Credit cards never logged
 - [ ] Retention policies configured
 
+### Rotation Checklist
+
+- [ ] Time-based rotation set (`rollingInterval: Day` or equivalent)
+- [ ] Size-based rotation set with `rollOnFileSizeLimit: true` (or equivalent)
+- [ ] `fileSizeLimitBytes` explicitly configured (default cap is hostile)
+- [ ] `retainedFileCountLimit` ≥ N×7 to cover within-window rolls
+- [ ] 90% size SOP defined: investigate noise root cause, do not just raise cap
+
 ---
 
 **Related Standards:**
@@ -635,6 +754,7 @@ App cannot continue?         → FATAL
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.3.0 | 2026-05-26 | Added: Log File Rotation Policy — mandatory dual-trigger (time + size) rotation with hostile-default warning, recipes for .NET/Python/Java/Node, ops SOP (XSPEC-232 / closes issue #111) |
 | 1.2.0 | 2026-01-24 | Added: OpenTelemetry Semantic Conventions, Observability Three Pillars Integration, Log-based Alerting, Advanced Correlation Patterns |
 | 1.1.0 | 2026-01-05 | Added: References section with OWASP, RFC 5424, OpenTelemetry, and 12 Factor App |
 | 1.0.0 | 2025-12-30 | Initial logging standards |

package/bundled/core/packaging-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/packaging-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-04-15
+**Version**: 1.1.0
+**Last Updated**: 2026-05-26
 **Applicability**: Projects using a UDS-aware toolchain
 **Scope**: universal
 
@@ -194,6 +194,75 @@ A packaging run is considered **successful** when ALL of the following condition
 
 ---
 
+## Archive Format Integrity
+
+When a packaging step produces an archive (`.zip`, `.tar.gz`, `.tar.bz2`, etc.) that will be consumed by a deploy script, the **real binary format MUST match the file extension**. A file named `.zip` MUST be a real ZIP archive (PKZip magic `PK\x03\x04`), not a renamed tar archive.
+
+> **Why mandatory:** mismatched archive formats trigger silent failures downstream. PowerShell's `Expand-Archive` and `[System.IO.Compression.ZipFile]::ExtractToDirectory()` accept tar-renamed-to-`.zip` **without raising an error** — the file is read, nothing is extracted, no exception. If the next step of the deploy script is destructive (e.g., "delete current install directory"), the live install is destroyed with nothing to replace it.
+
+### Verification before publish
+
+Every packaging step that produces an archive **MUST** include format verification before declaring success. Minimum verification:
+
+| Format | Verification one-liner |
+|---|---|
+| `.zip` | `python -c "import zipfile; zipfile.ZipFile('out.zip').namelist()"` must succeed |
+| `.zip` (Unix) | `file out.zip` must report `Zip archive data`, **NOT** `POSIX tar archive` |
+| `.tar.gz` | `tar -tzf out.tar.gz >/dev/null` must succeed |
+| any | optional: hash a manifest of expected files and compare |
+
+Verification failure MUST abort the packaging pipeline before publish.
+
+### Platform-specific recipes
+
+**Windows — DO use:**
+
+```powershell
+# Option A: PowerShell built-in (produces real ZIP)
+Compress-Archive -Path "publish\*" -DestinationPath "dist\patch.zip" -Force
+
+# Option B: .NET API (produces real ZIP)
+Add-Type -Assembly System.IO.Compression.FileSystem
+[System.IO.Compression.ZipFile]::CreateFromDirectory(
+    "publish", "dist\patch.zip", "Optimal", $false
+)
+```
+
+**Windows — DO NOT use:**
+
+```bash
+# ❌ git-bash / busybox tar -a -cf is UNRELIABLE on Windows
+# The -a "auto by extension" flag produces a POSIX tar archive with .zip extension.
+# `file patch.zip` → "POSIX tar archive (GNU)"  (not "Zip archive data")
+cd publish && tar -a -cf "../dist/patch.zip" api/
+```
+
+**Unix-like — DO use:**
+
+```bash
+# Use 'zip' for ZIP archives (BSD/Linux)
+zip -r dist/patch.zip publish/
+
+# Use 'tar -czf' (without -a) for tar.gz archives — explicit, deterministic
+tar -czf dist/patch.tar.gz publish/
+
+# Verify before publishing
+file dist/patch.zip            # expect "Zip archive data"
+python -c "import zipfile; zipfile.ZipFile('dist/patch.zip').namelist()"
+```
+
+### Consumer-side defense
+
+Producers cannot guarantee that consumers verify. Consumers (deploy scripts) **MUST** verify archive integrity before any destructive action. See [Deployment Standards — Defensive Deployment Ordering](deployment-standards.md#defensive-deployment-ordering) for the consumer-side requirement.
+
+### Failure mode reference (real incident)
+
+A Windows IIS production deploy script (2026-05-24) used `tar -a -cf patch.zip api/` in git-bash to produce its release archive. The consumer-side PowerShell deploy script then ran `Expand-Archive` (silent no-op on the tar-renamed file), proceeded to `Remove-Item -Recurse` the live `apiDir`, then `Copy-Item` from a source that did not exist (because nothing had been extracted). The live install was wiped, AppPool stopped, and production was down for ~3 minutes until backup-based rollback completed.
+
+The combination of (a) producer using auto-extension tar and (b) consumer not verifying extract output destroyed the running install with no error raised at any step.
+
+---
+
 ## Related Standards
 
 - [Deployment Standards](deployment-standards.md) — Deploy stage that follows packaging
@@ -207,6 +276,7 @@ A packaging run is considered **successful** when ALL of the following condition
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-05-26 | Added: Archive Format Integrity section — real-format-must-match-extension rule, verification one-liners, Windows recipe DO/DON'T list, real incident reference (XSPEC-231 / closes issue #113) |
 | 1.0.0 | 2026-04-15 | Initial release — XSPEC-034 Phase 1 |
 
 ---