93a4a82bff
감사에서 나온 결론은 "그림은 지금 정확하지만 정확함을 지킬 장치가 없다" 였다. 코드 유래 리터럴 18개가 전부 코드와 일치하고 deliver 는 바이트 결정적인데, 드리프트를 막는 게이트·테스트·훅이 0개였고 문서에 적힌 재생성 절차는 그대로는 실행되지 않았다 — `archify` 실행 파일은 PATH 에 없고 실제로는 저장소 밖 전역 스킬을 node 로 불러야 한다. 다음 사람은 첫 명령에서 막혔을 것이다. scripts/rebuild-diagrams.ps1 validate -> deliver -> visual-check -> manifest scripts/update_diagram_manifest.py 수신증의 단일 작성자 docs/diagrams/manifest.json spec/html sha256 + generator 버전 tests/test_diagram_sync.py 게이트 14건 게이트는 브라우저도 Node 도 archify 도 없이 돈다. 산출물이 바이트 결정적이라 수신증 대조만으로 충분하고, 그래서 폐쇄망 CI 에서도 돈다. 두 사고 시나리오를 실제로 만들어 차단을 확인했다 — HTML 의 단어 하나를 고치면 html sha 가, spec 의 태그 하나를 고치면 spec sha 가 어긋나 verify 가 실패한다. 노드 id 가 HTML 에 data-node-id 로 박히므로 의미적 연결도 함께 본다. git 위생 두 건도 같이 정리했다. *.visual-check.json 이 개발 머신 절대 경로와 크롬 설치 경로를 평문으로 담은 채 미추적·비ignore 상태였다(24개) — 납품 저장소가 removable media 로 건너가는 구조라 한 번 커밋되면 제거가 어렵다. 그리고 15,000줄 생성 HTML 을 텍스트로 머지하려 드는 것을 막았다. 재생성해도 4종 sha256 이 전부 불변이라 바이트 결정성을 다시 확인했다. 감사에서 나온 나머지 부채(한글 폰트 미번들, 영어 뷰어 UI, architecture 좌표 하드코딩, lifecycle 손튜닝 8개소, 콘솔 CSP 비호환)는 PROJECT_MAP 부채 표와 다이어그램 절에 등재했다. 폰트와 UI 는 archify 쪽 한계라 spec 으로는 못 고친다. 검증: ruff clean, pytest 600 passed (게이트 +14). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BStHFrjQj2VypecSG9ex1V
98 lines
3.6 KiB
PowerShell
98 lines
3.6 KiB
PowerShell
<#
|
|
.SYNOPSIS
|
|
docs/diagrams 의 다이어그램 4종을 spec JSON 에서 다시 생성한다.
|
|
|
|
.DESCRIPTION
|
|
PROJECT_MAP 에 적혀 있던 "archify validate -> deliver -> visual-check" 절차는
|
|
그대로는 실행되지 않았다 - archify 라는 실행 파일이 PATH 에 없고, 실제로는
|
|
저장소 밖 사용자 전역 스킬을 node 로 불러야 한다. 이 스크립트가 그 절차다.
|
|
|
|
순서:
|
|
1. validate (--quality showcase) 합성/기하 검증
|
|
2. deliver 산출물 HTML 을 원자적으로 교체
|
|
3. visual-check 실제 브라우저 증거 (Chrome 필요)
|
|
4. manifest 갱신 tests/test_diagram_sync.py 의 수신증
|
|
|
|
산출물은 바이트 결정적이다. 그래서 4번의 수신증만으로 드리프트를 잡을 수 있고,
|
|
테스트는 브라우저도 Node 도 없이 돈다.
|
|
|
|
.PARAMETER SkipVisualCheck
|
|
3단계를 건너뛴다. Chrome 이 없는 빌드 호스트용. 건너뛰면 그 사실을 출력한다
|
|
(조용한 통과 금지).
|
|
|
|
.PARAMETER ArchifyHome
|
|
archify 스킬 경로. 기본값은 $env:ARCHIFY_HOME, 없으면 ~/.claude/skills/archify.
|
|
|
|
.EXAMPLE
|
|
.\scripts
|
|
ebuild-diagrams.ps1
|
|
.EXAMPLE
|
|
.\scripts
|
|
ebuild-diagrams.ps1 -SkipVisualCheck
|
|
#>
|
|
[CmdletBinding()]
|
|
param(
|
|
[switch]$SkipVisualCheck,
|
|
[string]$ArchifyHome
|
|
)
|
|
|
|
$ErrorActionPreference = 'Stop'
|
|
$repoRoot = Split-Path -Parent $PSScriptRoot
|
|
Set-Location -LiteralPath $repoRoot
|
|
|
|
if (-not $ArchifyHome) {
|
|
if ($env:ARCHIFY_HOME) { $ArchifyHome = $env:ARCHIFY_HOME }
|
|
else { $ArchifyHome = Join-Path $HOME '.claude/skills/archify' }
|
|
}
|
|
$cli = Join-Path $ArchifyHome 'bin/archify.mjs'
|
|
if (-not (Test-Path -LiteralPath $cli)) {
|
|
Write-Host "archify CLI not found: $cli" -ForegroundColor Red
|
|
Write-Host 'Set -ArchifyHome or $env:ARCHIFY_HOME to the archify skill directory.' -ForegroundColor Red
|
|
exit 1
|
|
}
|
|
|
|
# (type, basename) - tests/test_diagram_sync.py 및 update_diagram_manifest.py 와 같은 목록
|
|
$diagrams = @(
|
|
@{ Type = 'architecture'; Base = 'system-architecture' },
|
|
@{ Type = 'dataflow'; Base = 'evidence-dataflow' },
|
|
@{ Type = 'workflow'; Base = 'operator-review-workflow' },
|
|
@{ Type = 'lifecycle'; Base = 'submission-lifecycle' }
|
|
)
|
|
|
|
$failures = @()
|
|
$skipped = @()
|
|
|
|
foreach ($d in $diagrams) {
|
|
$spec = Join-Path $repoRoot ("docs/diagrams/{0}.{1}.json" -f $d.Base, $d.Type)
|
|
$html = Join-Path $repoRoot ("docs/diagrams/{0}.html" -f $d.Base)
|
|
|
|
Write-Host "`n=== $($d.Base) ($($d.Type)) ===" -ForegroundColor Cyan
|
|
|
|
& node $cli validate $d.Type $spec --quality showcase
|
|
if ($LASTEXITCODE -ne 0) { $failures += "validate:$($d.Base)"; continue }
|
|
|
|
& node $cli deliver $d.Type $spec $html --quality showcase
|
|
if ($LASTEXITCODE -ne 0) { $failures += "deliver:$($d.Base)"; continue }
|
|
|
|
if ($SkipVisualCheck) { $skipped += $d.Base; continue }
|
|
|
|
& node $cli visual-check $html
|
|
# exit 2 = skipped (Chrome/Chromium 부재). 실패와 구분해 기록한다.
|
|
if ($LASTEXITCODE -eq 2) { $skipped += $d.Base }
|
|
elseif ($LASTEXITCODE -ne 0) { $failures += "visual-check:$($d.Base)" }
|
|
}
|
|
|
|
Write-Host "`n=== manifest ===" -ForegroundColor Cyan
|
|
& python (Join-Path $PSScriptRoot 'update_diagram_manifest.py')
|
|
if ($LASTEXITCODE -ne 0) { $failures += 'manifest' }
|
|
|
|
Write-Host ''
|
|
if ($skipped.Count -gt 0) {
|
|
Write-Host "VISUAL-CHECK SKIPPED (no browser evidence): $($skipped -join ', ')" -ForegroundColor Yellow
|
|
}
|
|
if ($failures.Count -gt 0) {
|
|
Write-Host "REBUILD FAILED: $($failures -join ', ')" -ForegroundColor Red
|
|
exit 1
|
|
}
|
|
Write-Host 'REBUILD OK - run verify.ps1 to confirm the diagram gate' -ForegroundColor Green
|
|
exit 0
|