Files
clean-architecture-frontend…/docs/history/plans/2026-08-02-security-finalizer.md
DongHyeonka 75fad73a7d docs(records): 기록·설계서·결정 기록 67개에 한국어 머리 블록을 단다
문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금
정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture
목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어
값을 쓴다.

고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은
한 글자도 고치지 않는다. 상태는 기계 변환이다.
- 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면
  확인 안 함 (채택 4, 확인 안 함 21)
- 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는
  같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5,
  확인 안 함 14. 이미 블록이 있던 5개는 그대로)
- 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에
  있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터
  한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다.
- 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일.

위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서
고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다.
보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는
문서나 코드 경로만 쓴다.

검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가
같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
2026-11-08 17:25:41 +09:00

5.8 KiB

기록 · 계획서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 확인 안 함
  • 작성일: 2026-08-02
  • 요약: 캡처한 불변 후보를 무작위 비공개 staging 폴더 하나에 다섯 파일과 v3 검증 기록으로 마무리하는 구현 계획이다.
  • 현재 정본: scripts/lib/promotion-stager.ts, scripts/lib/stage-verified-promotion-cli.ts

Security Finalizer Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Finalize a captured immutable candidate into one private random exact-five staging directory with strict v3 verification records and deterministic cleanup.

Architecture: finalizeVerifiedPromotion captures the archive, provider reports, and public keys before validation, evaluates only those captured bytes against archived local evidence, generates both v3 records in memory, and publishes five read-only files under a descriptor-relative runner-temp directory. The generated workflow consumes the returned staging path immediately and always invokes the token-bound cleanup CLI.

Tech Stack: Node.js 24, TypeScript, Zod, Vitest, bubblewrap-independent filesystem primitives, generated Gitea Actions YAML.

Global Constraints

  • Never accept pre-existing provider- or promotion-verification JSON as an input.
  • Stage exactly archive, vulnerability report, provenance attestation, provider verification v3, and promotion verification v3.
  • Use injected time and randomness for deterministic tests.
  • Use a random runner-temp directory at mode 0700, files at 0400, and O_EXCL | O_NOFOLLOW creation.
  • Do not claim that TypeScript closes the Gitea upload action pathname-reopen issue or guarantees renameat2 semantics.

Task 1: Exact-five finalizer contract

Files:

  • Modify: tests/unit/ci-artifact-contract.test.ts
  • Modify: scripts/lib/promotion-stager.ts
  • Modify: scripts/contracts/promotion-artifacts.ts

Interfaces:

  • Consumes: finalizeVerifiedPromotion(input, dependencies) with captured archive/report/key inputs.

  • Produces: { stagingRoot, cleanupToken, files } where files is the canonical exact-five name/digest list.

  • Step 1: Write failing tests for no pre-existing records, strict distinct v3 roles, exact provider-record and local-assessment hashes, full run/source/candidate/nonces/key/trust bindings, key rotation, captured-source mutation, and no output on failures.

  • Step 2: Run RED: corepack pnpm exec vitest run tests/unit/ci-artifact-contract.test.ts -t "verified promotion finalizer" --maxWorkers=1 and retain the first contract failure.

  • Step 3: Implement minimal finalizer changes so all validation and record generation consume captured bytes and both PASS records are created only after local/provider PASS.

  • Step 4: Run GREEN: rerun the focused Vitest command and require zero failures.

Task 2: Private staging and cleanup

Files:

  • Modify: tests/unit/ci-artifact-contract.test.ts
  • Modify: scripts/lib/promotion-stager.ts
  • Modify: scripts/cleanup-verified-promotion.ts

Interfaces:

  • Consumes: injected randomBytes, runner-temp root, cleanup token.

  • Produces: descriptor-relative random staging at 0700, exact files at 0400, and token-bound cleanup.

  • Step 1: Write failing tests for deterministic naming, modes, stable-path absence, exclusive no-follow creation, parent/leaf substitution, success cleanup, and failure cleanup.

  • Step 2: Run RED: use the Task 1 focused Vitest command and retain the first filesystem-boundary failure.

  • Step 3: Implement minimal private publication and cleanup changes using /proc/self/fd where available, bounded writes, identity rechecks, and removal of owned partial roots.

  • Step 4: Run GREEN: rerun the focused Vitest command and require zero failures.

Task 3: Workflow handoff

Files:

  • Modify: config/ci/gates.json
  • Modify: scripts/contracts/ci-gates.ts
  • Modify: scripts/stage-verified-promotion.ts
  • Modify: .gitea/workflows/quality-gates.yml
  • Modify: tests/unit/ci-workflow-generation.test.ts

Interfaces:

  • Consumes: finalizer step outputs staging_root and cleanup_token.

  • Produces: setup, three downloads, finalizer, immediate non-always() exact-five upload, and always() cleanup ordering.

  • Step 1: Write/update failing workflow assertions that reject standalone extraction, stable staging paths, missing --ignore-scripts, upload indirection, or cleanup ordering drift.

  • Step 2: Run RED: node scripts/generate-ci-workflow.ts --check and the workflow snapshot test.

  • Step 3: Update the CI contract/config and regenerate YAML with the finalizer output path and cleanup environment.

  • Step 4: Run GREEN: require workflow byte check and snapshot test PASS.

Task 4: Full verification and durable report

Files:

  • Modify: .superpowers/sdd/2026-08-01-quality-architecture-remediation/task-3-report.md

Interfaces:

  • Consumes: focused finalizer, provider, workflow, type, and lint evidence.

  • Produces: durable RED/GREEN evidence and a commit-ready report without overclaiming platform handoff guarantees.

  • Step 1: Run verification: focused finalizer/provider tests, check:supply-chain:provider-fixtures, workflow --check, check:types, and lint.

  • Step 2: Append exact RED/GREEN commands and outcomes to the task report, including the remaining Gitea upload and renameat2 limitations.

  • Step 3: Inspect diff/status and report completion before committing.