SDD Template Updater (/sdd-template-update)

Output language: All output mirrors the language of the invoking prompt. Vietnamese prompt → Vietnamese output; English prompt → English output. Canonical tokens (PENDING HUMAN REVIEW, APPROVED, SAFE, STAGED, NEVER, UP-TO-DATE, OUTDATED), file paths, and CLI commands are language-invariant.

Dùng sau khi chạy scripts/update.sh hoặc scripts/update.ps1 để kiểm tra kết quả và hướng dẫn merge governance files.

Tham số

• --template=<path>: Tùy chọn; path tới template nguồn. Không truyền thì dùng template-source trong .sdd/template-version.md.
• --check: Chỉ so sánh version và báo cáo drift — không chạy update script.
• --review: So sánh staged governance files (.sdd/updates/) với bản hiện tại và đề xuất merge.

Phân loại file theo chiến lược update

Loại	Files	Hành động
SAFE — template-owned	.claude/skills/**, docs/sdd-add-quickstart.md, docs/sdd-add-guide.md, docs/sdd-add-field-guide.md, docs/sdd-add-scenario-playbook.md, docs/architecture-profile-guide.md, docs/multi-agent-orchestration-guide.md, scripts/adopt.sh, scripts/adopt.ps1, scripts/self-heal.sh, scripts/template-smoke.sh, scripts/template-smoke.ps1, scripts/start-claude.sh, scripts/start-claude.ps1, scripts/update.sh, scripts/update.ps1	Overwrite trực tiếp; không chứa customization của user.
STAGED — cần review	CONSTITUTION.md, AGENTS.md, CLAUDE.md, .agentignore	Copy vào .sdd/updates/; user merge thủ công sau khi AI review diff.
NEVER — user-owned	.sdd/architecture-profile.md, .sdd/README.md, .sdd/shared_context.md, .sdd/mcp-config.yaml, .sdd/features/, .sdd/reviews/, .sdd/rfcs/, .sdd/constraints/	Không bao giờ overwrite; chứa quyết định kiến trúc và feature work của user.

Quy trình

1. --check — kiểm tra version drift

1. Đọc .sdd/template-version.md: template-version, adopted-at, last-updated, template-source.
2. Nếu có --template hoặc template-source hợp lệ, đọc .sdd/template-version.md của template nguồn và so sánh version.
3. Báo cáo version đang dùng vs template, số ngày từ last-updated, lệnh update theo OS.

TEMPLATE VERSION CHECK
Installed : v{installed}  (last updated: {last-updated})
Template  : v{template}   (source: {template-source})
Status    : UP-TO-DATE | OUTDATED
Next step : {update command}

2. (không flag) — chạy update script

1. Xác định OS (Windows → PowerShell, Linux/macOS → Bash).
2. Xác nhận template-source từ .sdd/template-version.md hoặc --template.
3. Hiển thị lệnh update và chờ Human reviewer có thẩm quyền xác nhận trước khi chạy.
4. Sau khi chạy, kiểm tra .sdd/updates/ và tự động chuyển sang --review nếu có staged files.

# Linux / macOS
./scripts/update.sh <template-path>

# Windows PowerShell
.\scripts\update.ps1 <template-path>

Thêm --dry-run để xem trước. --force-governance chỉ overwrite AGENTS.md, CLAUDE.md và .agentignore với backup; CONSTITUTION.md luôn stage và chỉ được merge sau RFC APPROVED.

3. --review — review staged governance files

1. Kiểm tra .sdd/updates/ có file không; nếu không có, báo không cần merge.
2. Với mỗi staged file, so sánh với bản hiện tại và liệt kê:
   • Section/block mới trong template.
   • Section/block hiện tại có thể bị ảnh hưởng.
   • Đề xuất merge action: keep, replace, merge-manually.
3. Tạo AI recommendation theo .claude/skills/_shared/ai-review-protocol.md.
4. Human reviewer có thẩm quyền quyết định merge action; Agent không tự merge hoặc overwrite governance files.

STAGED GOVERNANCE REVIEW
─────────────────────────────────────────────
File: AGENTS.md
  Current version  : v{x}
  Template version : v{y}
  New in template  : {description}
  Conflict risk    : LOW | MEDIUM | HIGH
  Recommendation   : {keep | replace | merge-manually}
  Action required  : {next command or manual step}
─────────────────────────────────────────────
Next step: Merge manually → delete .sdd/updates/ → commit

AI Recommendation và Human Final Review

Sau khi chạy --review, tạo canonical recommendation từ .claude/skills/_shared/ai-review-protocol.md, gồm staged files, diff summary, merge risk, action đề xuất và NEVER-file nào không nên đụng tới. Lưu tại .sdd/reviews/update-<timestamp>.md với PENDING HUMAN REVIEW. Human reviewer có thẩm quyền quyết định merge action; Agent không tự merge, overwrite hoặc xoá staged files.

Safety gates

• Không bao giờ đề xuất ghi vào NEVER files.
• CONSTITUTION.md luôn chỉ stage, kể cả --force-governance; thay đổi Layer 1/2 cần RFC qua /sdd-rfc trước khi merge.
• AGENTS.md thay đổi permission cần Human reviewer có thẩm quyền approval theo /sdd-agents-edit.
• Agent không tự chạy update script mà không có xác nhận explicit của Human reviewer có thẩm quyền.
• Nếu template-source không xác định được và không có --template, dừng và yêu cầu Human cung cấp path.

Hướng dẫn sử dụng

• Khi dùng: Check template drift or review staged update files after the update script.
• Không dùng: Không dùng để tự merge, overwrite NEVER files, delete staged files, or bypass RFC/permission review.
• Input: Optional --template, --check, --review; reject unknown source and direct NEVER-file target.
• Điều kiện trước: .sdd/template-version.md or explicit source is readable; update script requires Human confirmation before running.
• Evidence: Version report, SAFE/STAGED/NEVER classification, staged diff and .sdd/reviews/update-<timestamp>.md.
• Dừng khi: Missing source, version conflict, merge conflict, NEVER write attempt or missing Human merge decision.
• Human quyết định: Human decides staged governance merge; Agent only reports and preserves staged material.
• Lệnh tiếp theo: /sdd-template-update --check for drift, or /sdd-review --target=.sdd/reviews/update-<timestamp>.md --status=APPROVED ... before the persisted merge action.
• Ví dụ: /sdd-template-update --review compares .sdd/updates/AGENTS.md without merging it.

Completion output

Dùng Completion output contract. Tóm tắt UP-TO-DATE/OUTDATED, SAFE/STAGED/NEVER, staged file và review evidence. OUTDATED có template source hợp lệ chỉ có thể continue bằng update command đã hiển thị sau explicit Human confirmation; staged governance là Human decision required, Human reviewer có thẩm quyền ghi decision, reviewer identity và Follow-up không phải placeholder bằng /sdd-review --target=.sdd/reviews/update-<timestamp>.md --status=<APPROVED|REVISE|REJECTED> --decision="<human decision>" --reviewer="<authorized human reviewer>" --follow-up="<exact next command or required action>". Missing source, merge conflict hoặc NEVER write attempt là BLOCKED; không tự chạy update, merge, overwrite hoặc xóa staged files.