universal-dev-standards 5.11.0 → 5.13.2

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/ai/standards/test-governance.ai.yaml

@@ -158,3 +158,22 @@ standard:
       evidence: >
         BUG-A08 post-mortem (2026-04-20): 22 tests existed in UDS but were never
         executed by any CI gate, passing silently and masking real failures.
+
+    - id: gate-wiring-required
+      trigger: adding any quality detection script to the repository
+      instruction: |
+        Quality detection scripts (anti-fake check, stub check, coverage ratchet,
+        tautology scanner) MUST appear in at least one CI workflow job AND at least
+        one local hook (pre-commit or pre-push). A script that exists in scripts/
+        but is never called by CI is equivalent to not existing and constitutes a
+        governance gap. Apply the same execution-continuity principle to detection
+        scripts as to test cases: existence ≠ execution.
+        Checklist when adding a detection script:
+          [ ] Script is called in .github/workflows/*.yml (at least one job)
+          [ ] Script is called in .husky/pre-commit or .husky/pre-push
+          [ ] CI step name references the XSPEC or standard that mandates it
+      priority: required
+      evidence: >
+        XSPEC-220 post-mortem (2026-05-19): check-anti-fake-tests.sh existed in
+        vibeops/scripts/ for months but was not called by pre-commit, allowing
+        tautology assertions to be committed undetected.

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/license-compliance.md

@@ -0,0 +1,118 @@
+# License Compliance Standards
+
+> **Version**: 2.1.0 | **Status**: Active | **Updated**: 2026-05-16
+> **AI-optimized version**: `ai/standards/license-compliance.ai.yaml`
+> **Agent Spec**: ASPEC-001 (cross-project/aspec/ASPEC-001-license-compliance-agent.md)
+
+## Overview
+
+Comprehensive license compliance for AI-augmented development, covering both general OSS practice (Tier 1) and AI-specific rules for AI-generated code (Tier 2).
+
+## Tier 1 — General OSS Compliance Practices
+
+Applies to every project regardless of AI use.
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | License classification and allowlist | MUST |
+| REQ-002 | Automated license scanning in CI | MUST |
+| REQ-003 | SBOM generation (CycloneDX 1.5 or SPDX 2.3) | MUST |
+| REQ-004 | License attribution and NOTICES file | MUST |
+| REQ-005 | License violation remediation (5 business days) | MUST |
+| REQ-006 | License review for new technology adoption | SHOULD |
+
+### License Tiers
+
+| Tier | Licenses | Action |
+|------|----------|--------|
+| APPROVED | MIT, Apache 2.0, BSD-2/3-Clause, ISC, CC0 | Auto-approve |
+| REVIEW-REQUIRED | LGPL-2.1/3.0, MPL-2.0, CDDL | Legal review before adoption |
+| PROHIBITED | GPL-2.0/3.0, AGPL-3.0, SSPL-1.0, BUSL-1.1 | Block PR immediately |
+
+## Tier 2 — AI-Specific Rules
+
+Binding on AI Agents that produce code (VibeOps Generator Agent and equivalents).
+
+| ID | Rule | Severity |
+|----|------|----------|
+| LC-001 | SPDX ID lookup required | Blocking |
+| LC-002 | Blocklist auto-block | Blocking |
+| LC-003 | Allowlist auto-approve | Informational |
+| LC-004 | Greylist human review | Review required |
+| LC-005 | SBOM mandatory generation | Blocking |
+| LC-006 | Copyright similarity threshold (≥0.85 block) | Blocking |
+| LC-007 | PII pattern detection | Review required |
+| LC-008 | EU AI Act transparency marker | Blocking |
+| LC-009 | Customer policy ceiling | Informational |
+
+## v2.1.0 Enhancements (XSPEC-193 Phase 2)
+
+### ClearlyDefined API (LC-001)
+
+- Primary license lookup source: `https://api.clearlydefined.io/definitions/{type}/{provider}/{namespace}/{name}/{revision}`
+- Confidence ≥ 0.95 for well-known packages (score.total ≥ 80)
+- 24h TTL LRU cache (cap=500) + negative cache for 404
+- Token bucket: 10 req/s, burst 20
+- Retry strategy: 5xx → exponential backoff × 3 (200ms/1s/3s); 429 → batch fallback
+- DEC-064 cache key isolation: `sha256(client_salt + ':' + purl)`
+
+### AST PII Analysis (LC-007)
+
+- Tree-sitter support: TypeScript, JavaScript, Python
+- Context classification:
+  - `hardcoded_value` → severity upgraded to `critical`
+  - `comment` → severity downgraded to `info`
+  - `schema_field` → annotated, no severity change
+- `// pii:ignore` pragma: suppresses findings on same line
+- Optional fields: `PIIPattern.confidence`, `PIIPattern.ast_context`
+- Graceful fallback to regex when tree-sitter unavailable
+
+### EmbeddingProvider Strategy (LC-006)
+
+- `provider='onnx-minilm'`: ONNX local inference (all-MiniLM-L6-v2)
+- `provider='ollama-bge-m3'`: Ollama local API (localhost:11434)
+- `provider='jaccard'`: Jaccard token similarity (Phase 1 baseline, default)
+- In-memory snippet index (`buildSnippetIndex()`) per-customer (DEC-064 salt)
+- External search: opt-in via `enableExternalSearch=true` (default=false)
+
+## Principles
+
+| ID | Principle |
+|----|-----------|
+| P-1 | SPDX First — all license IDs must be SPDX standard |
+| P-2 | Independent Evaluator — different model class from Generator |
+| P-3 | Evidence-Based Decision — every block carries traceable evidence |
+| P-4 | Transparency by Default — EU AI Act Article 50 markers required |
+| P-5 | Customer Sovereignty — policy customizable within EULA §9 limits |
+
+## Tool Sequence (XSPEC-193 §2)
+
+```
+1. dependency_reader
+2. license_lookup         ← ClearlyDefined API (v2.1.0)
+3. license_blocklist_check
+4. sbom_generator
+5. pii_pattern_detector   ← AST-enhanced (v2.1.0)
+6. copyright_similarity_check ← EmbeddingProvider (v2.1.0)
+7. eu_ai_act_classifier
+8. transparency_marker
+9. block_pr
+10. suggest_alternative
+11. escalate_to_human
+```
+
+## Related Specs
+
+- XSPEC-193 — License Compliance Agent complete spec
+- XSPEC-066 — Wave 3 Compliance Pack (v1.0.0 baseline)
+- DEC-063 — VibeOps legal & compliance strategy
+- DEC-064 — Customer IP isolation (cache salt)
+- ASPEC-001 — License Compliance Agent SPEC (XSPEC-205 §REQ-2 format)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-04-30 | Initial — REQ-001~006 general OSS practices |
+| v2.0.0 | 2026-05-14 | Added Tier 2 LC-001~009 AI-specific rules |
+| v2.1.0 | 2026-05-16 | ClearlyDefined API + AST PII + EmbeddingProvider + ASPEC-001 ref |

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 |
 
 ---