fix: prepare design-workflow v0.2.1

.github/workflows/ci.yml

@@ -50,13 +50,17 @@ jobs:
           python-version: "3.12"
       - name: Build deterministic archive twice
         run: |
-          python scripts/package_skill.py --version 0.2.0 --output-dir dist-a
-          python scripts/package_skill.py --version 0.2.0 --output-dir dist-b
-          cmp dist-a/design-workflow-0.2.0.zip dist-b/design-workflow-0.2.0.zip
+          version=$(<VERSION)
+          python scripts/package_skill.py --output-dir dist-a
+          python scripts/package_skill.py --output-dir dist-b
+          python scripts/package_project.py --output-dir dist-a
+          python scripts/package_project.py --output-dir dist-b
+          cmp "dist-a/design-workflow-${version}.zip" "dist-b/design-workflow-${version}.zip"
+          cmp "dist-a/design-workflow-project-${version}.zip" "dist-b/design-workflow-project-${version}.zip"
       - uses: actions/upload-artifact@v4
         with:
           name: design-workflow-ci-package
           path: |
-            dist-a/design-workflow-0.2.0.zip
-            dist-a/design-workflow-0.2.0.zip.sha256
+            dist-a/design-workflow-*.zip
+            dist-a/design-workflow-*.zip.sha256
           if-no-files-found: error

.github/workflows/release.yml

@@ -26,6 +26,13 @@ jobs:
           python scripts/validate_project.py
           agentskills validate design-workflow
           python -m unittest discover -s tests -v
+      - name: Verify tag matches VERSION
+        run: |
+          version=$(<VERSION)
+          if [[ "$GITHUB_REF_NAME" != "v${version}" ]]; then
+            echo "release tag $GITHUB_REF_NAME does not match VERSION $version" >&2
+            exit 1
+          fi
       - name: Build release archive
         run: python scripts/package_skill.py --version "$GITHUB_REF_NAME"
       - name: Create verified GitHub Release

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes are documented here.
 
+## [0.2.1] - 2026-07-20
+
+### Added
+
+- root `VERSION` as the single release-version source of truth
+- provenance schema for v0.2.1+ semantic forward-test results, including
+  execution, commit, model, suite, observed-route, and boundary-rationale fields
+
+### Changed
+
+- replaced the route contract's physical artifact flag with
+  `meaningful_design_exists`
+- allowed `create` contracts to preserve partial structural evidence such as a
+  wireframe while establishing a new visual system
+- required release tags and explicit package versions to match `VERSION`
+- restricted runtime skill ZIP contents to documented files and directories,
+  rejecting hidden, temporary, archive, symlink, credential-like, unexpected,
+  and oversized entries
+- made the semantic grader require provenance and per-case boundary rationales
+  for new-schema results while retaining v0.2.0 records unchanged
+
 ## [0.2.0] - 2026-07-17
 
 ### Added

CONTRIBUTING.md

@@ -24,8 +24,8 @@ python -m pip install -r requirements-dev.txt
 python scripts/validate_project.py
 agentskills validate design-workflow
 python -m unittest discover -s tests -v
-python scripts/package_skill.py --version 0.2.0
-python scripts/package_project.py --version 0.2.0
+python scripts/package_skill.py
+python scripts/package_project.py
 ```
 
 Open a pull request only after all commands pass and any changed semantic

README.ko.md

@@ -57,6 +57,11 @@ Use $design-workflow to polish the existing checkout without changing its layout
 python design-workflow/scripts/validate_route_contract.py contract.json
 ```
 
+계약의 `meaningful_design_exists`는 파일 존재 여부가 아니라 증거에 보존해야
+할 확립된 디자인 체계가 있는지를 뜻합니다. 따라서 wireframe이 있어도 의미
+있는 시각 체계가 없다면 `false`인 `create`를 사용하고 content order와
+information architecture를 `fixed`에 기록할 수 있습니다.
+
 ## 개발 및 검증
 
 Python 3.11 이상을 사용합니다.
@@ -66,34 +71,63 @@ python -m pip install -r requirements-dev.txt
 python scripts/validate_project.py
 agentskills validate design-workflow
 python -m unittest discover -s tests -v
-python scripts/package_skill.py --version 0.2.0
-python scripts/package_project.py --version 0.2.0
+python scripts/package_skill.py
+python scripts/package_project.py
 ```
 
-CI는 구조, 공식 Agent Skills 형식, 변경 경계 계약, 평가 fixture 품질,
-재현 가능한 패키징을 검증합니다. 실제 의미 라우팅은
-`evals/semantic-smoke.json`을 클라이언트에서 실행하고 다음 명령으로
-채점합니다.
+루트의 `VERSION`이 릴리스 버전의 단일 기준입니다. 두 패키징 명령은 이를
+기본으로 읽으며, 선택적으로 전달한 `--version`도 반드시 일치해야 합니다.
+
+결정적인 단위·불변식 검증은 구조, 공식 Agent Skills 형식, route contract,
+fixture 정합성, 패키지 allowlist와 재현 가능한 ZIP을 검사하며 모델을
+실행하지 않습니다. 실제 의미 라우팅은 `evals/semantic-smoke.json`을
+클라이언트에서 실행하고 다음 명령으로 별도 채점합니다.
 
 ```bash
 python scripts/grade_semantic_results.py path/to/client-result.json
 ```
 
-스킬 활성화는 모델과 클라이언트에 따라 비결정적입니다.
+스킬 activation test는 모델과 클라이언트에 따라 비결정적입니다.
 `evals/trigger-cases.json`은 반복 활성화 평가를 위한 균형 잡힌 긍정·근접
 부정 사례이며, 이를 정적 단위 테스트 결과로 과장하지 않습니다.
+Semantic forward test 역시 기록된 한 client·model·commit·suite revision의
+post-activation 동작만 보여줍니다. v0.2.1부터 원시 결과는
+[`evals/semantic-result.schema.json`](evals/semantic-result.schema.json)을 따르고
+실행 시각, commit SHA, skill version, runner, 모델, reasoning effort, suite
+provenance, 실제 route와 boundary 근거를 기록해야 합니다. 자세한 절차는
+[`evals/README.md`](evals/README.md)에 있습니다.
+
+grader는 필드 완전성, route 일치, 실행자가 선언한 boundary 판정과 근거
+존재를 확인할 뿐 실제 응답이 경계를 지켰다고 독립적으로 의미 판정하지
+않습니다. 사람 또는 별도 모델이 근거와 안전하게 기록된 응답 일부를
+expected boundary와 대조해야 합니다.
 
 ### 현재 검증 결과
 
 - 프로젝트·링크 검증: 통과
 - 공식 `agentskills` 형식 검증: 통과
-- 의존성 없는 단위 테스트: 13/13 통과
-- 독립 에이전트 의미 라우팅 forward test: 8개 경로 16/16 통과
+- 의존성 없는 단위 테스트: 이 revision에서 22/22 통과
+- 과거 v0.2.0 post-activation semantic forward test: 8개 경로 16/16 기록;
+  v0.2.1 결과로 재실행하거나 이름을 바꾸지 않음
 - 재현 가능한 아카이브와 최상위 폴더 검증: 통과
 
-원시·채점 결과는 `evals/results/`에 있습니다. 이는 스킬이 로드된 뒤의
-라우팅을 검증하며, 모든 모델과 클라이언트의 활성화 정확도를 주장하지
-않습니다.
+원시·채점 결과는 `evals/results/`에 있습니다. 이는 기록된 실행에서 스킬이
+로드된 뒤의 라우팅을 보여주며, 모든 모델·클라이언트의 activation 정확도나
+독립적으로 입증된 semantic boundary를 주장하지 않습니다.
+
+릴리스 skill ZIP은 명시적 파일·디렉터리 allowlist를 사용합니다. 생성된
+Python cache는 제외합니다. 숨김 파일, 임시·백업 파일, ZIP/checksum, symlink,
+credential로 보이는 파일명, 예상하지 않은 형식과 대형 파일이 있으면
+조용히 포함하지 않고 패키징을 실패시킵니다. 저장소 문서·eval·tests는
+runtime skill ZIP에 포함되지 않습니다.
+
+## 릴리스
+
+1. `VERSION`과 `CHANGELOG.md`를 갱신합니다.
+2. 위 검증 명령을 모두 실행합니다.
+3. `git tag "v$(<VERSION)"`처럼 `VERSION`에서 tag를 생성해 push합니다.
+4. release workflow는 `GITHUB_REF_NAME == "v" + VERSION`을 요구합니다.
+   불일치하면 GitHub Release를 만들기 전에 실패합니다.
 
 ## 라이선스와 출처
 

README.md

@@ -36,6 +36,7 @@ design-workflow-project/
 │   ├── NOTICE
 │   └── THIRD_PARTY_NOTICES.md
 ├── evals/                       # route, trigger, and semantic smoke cases
+├── VERSION                      # single release-version source of truth
 ├── scripts/                     # project validation, grading, and packaging
 ├── tests/                       # dependency-free unit tests
 └── .github/workflows/           # CI and tagged release automation
@@ -90,6 +91,11 @@ validate it without third-party dependencies:
 python design-workflow/scripts/validate_route_contract.py contract.json
 ```
 
+The contract's `meaningful_design_exists` field describes whether evidence
+contains an established design system that must be preserved, not whether any
+file exists. A wireframe can therefore use `create` with the field set to
+`false`, while recording content order and information architecture in `fixed`.
+
 ## Development and verification
 
 Use Python 3.11 or newer.
@@ -99,43 +105,66 @@ python -m pip install -r requirements-dev.txt
 python scripts/validate_project.py
 agentskills validate design-workflow
 python -m unittest discover -s tests -v
-python scripts/package_skill.py --version 0.2.0
-python scripts/package_project.py --version 0.2.0
+python scripts/package_skill.py
+python scripts/package_project.py
 ```
 
-The deterministic CI checks structure, official Agent Skills conformance, route
-contract invariants, eval fixture quality, and reproducible packaging. Semantic
-behavior is evaluated separately with `evals/semantic-smoke.json`; record a
-client run and grade it with:
+`VERSION` is the release source of truth. Both package commands read it by
+default; an optional `--version` must match it.
+
+Deterministic unit and invariant checks cover structure, official Agent Skills
+conformance, route contracts, fixture consistency, package allowlists, and
+reproducible archives. They do not execute a model. Semantic behavior is tested
+separately with `evals/semantic-smoke.json`; record a client run and grade it
+with:
 
 ```bash
 python scripts/grade_semantic_results.py path/to/client-result.json
 ```
 
-Trigger behavior is client- and model-dependent. `evals/trigger-cases.json`
-contains balanced positive and near-miss prompts for repeated client-specific
-activation tests; it is not presented as a deterministic unit test.
+Trigger/activation behavior is client- and model-dependent.
+`evals/trigger-cases.json` contains balanced positive and near-miss prompts for
+repeated client-specific activation tests; it is not a deterministic unit test.
+Semantic forward tests likewise describe one recorded client, model, commit, and
+suite revision. From v0.2.1 onward, raw results must follow
+[`evals/semantic-result.schema.json`](evals/semantic-result.schema.json) and
+record execution time, commit, skill version, runner, model, reasoning effort,
+suite provenance, observed routes, and boundary rationales. See
+[`evals/README.md`](evals/README.md) for the protocol.
+
+The grader can verify field completeness, route equality, and a declared
+boundary decision. It cannot independently infer that a response preserved the
+boundary. A person or separate model must review each rationale (and any safely
+recorded response excerpt) against the expected boundary.
 
 ### Current verification evidence
 
 - project and link validator: passed
 - official `agentskills` format validator: passed
-- dependency-free unit tests: 13/13 passed
-- independent post-activation semantic forward test: 16/16 passed across all
-  eight routes
+- dependency-free unit tests: 22/22 passed for this revision
+- historical v0.2.0 post-activation semantic forward test: 16/16 recorded across
+  all eight routes; it was not rerun or relabeled for v0.2.1
 - deterministic archive equality and root-directory checks: passed
 
-The raw and graded forward-test records are stored in `evals/results/`. These
-results demonstrate route selection after the skill is loaded; they do not claim
-universal activation accuracy across every client or model.
+The raw and graded forward-test records are stored in `evals/results/`. They
+demonstrate route selection after the skill was loaded in the recorded run; they
+do not claim universal activation accuracy or independently proven semantic
+boundaries across every client or model.
+
+Release skill ZIPs use an explicit file and directory allowlist. Generated
+Python caches are excluded. Hidden files, temporary or backup files,
+archives/checksums, symlinks, credential-like names, unexpected types, and
+oversized files fail packaging instead of being silently shipped. Repository
+docs, evals, and tests remain outside the runtime skill ZIP.
 
 ## Release
 
 1. Update `CHANGELOG.md`.
 2. Run all verification commands above.
-3. Push a semantic-version tag such as `v0.2.0`.
-4. The release workflow validates the project, builds the deterministic archive,
-   verifies the tag, and creates a GitHub Release with the archive and checksum.
+3. Create and push the tag from `VERSION`, for example `git tag "v$(<VERSION)"`.
+4. The release workflow requires `GITHUB_REF_NAME == "v" + VERSION`, validates
+   the project, builds the deterministic archive, verifies the tag, and creates
+   a GitHub Release with the archive and checksum. A mismatch stops the release.
 
 ## License and provenance
 

SOURCE_AUDIT.md

@@ -1,7 +1,7 @@
 # Source and License Audit
 
-Audit date: 2026-07-17
-Release target: v0.2.0
+Audit date: 2026-07-20
+Release target: v0.2.1
 
 ## Repository license
 

VERSION

@@ -0,0 +1 @@
+0.2.1

design-workflow/SKILL.md

@@ -30,8 +30,11 @@ or *add* as local-change language. Do not interpret them as redesign permission.
    [references/routing.md](references/routing.md) for ambiguous, mixed, partial,
    or cross-medium requests.
 4. **Set the change contract.** Record what is fixed, what may change, the
-   governing evidence, unknowns, and redesign authorization. For ambiguous or
-   high-impact work, start from [assets/route-contract.example.json](assets/route-contract.example.json)
+   governing evidence, unknowns, whether a meaningful design system exists, and
+   redesign authorization. Input files alone do not establish a meaningful
+   design: a wireframe or text brief can fix structure while leaving visual
+   direction open. For ambiguous or high-impact work, start from
+   [assets/route-contract.example.json](assets/route-contract.example.json)
    and run `python scripts/validate_route_contract.py <contract.json>`.
 5. **Load only the route-specific reference.** Follow the reference map below.
 6. **Execute through the right medium workflow.** Reuse the target project's
@@ -88,8 +91,9 @@ reference silently override an established project system.
 ## Gotchas
 
 - A new page in an existing product is normally `expand`, not `create`.
-- A low-fidelity artifact may fix structure without fixing visual language; use
-  a mixed contract instead of pretending everything is fixed or unconstrained.
+- A low-fidelity artifact may fix structure without constituting a meaningful
+  existing design. It can use `create` with `meaningful_design_exists=false`,
+  structural dimensions fixed, and visual dimensions changeable.
 - `Modernize` under `preserve` permits local corrections, not wholesale token,
   layout, or brand replacement.
 - Adding a new sibling asset is `expand`; adapting a specific source artifact to

design-workflow/assets/route-contract.example.json

@@ -1,18 +1,21 @@
 {
-  "primary_route": "preserve",
+  "primary_route": "create",
   "secondary_routes": [],
-  "artifact_exists": true,
+  "meaningful_design_exists": false,
   "redesign_authorized": false,
   "governing_evidence": [
-    "path or description of the editable source"
+    "wireframe with approved content order"
   ],
   "fixed": [
     "information architecture",
-    "brand identity"
+    "content order"
   ],
   "changeable": [
-    "local spacing and responsive defects"
+    "visual language",
+    "typography",
+    "palette",
+    "component styling"
   ],
   "unknowns": [],
-  "mutation_scope": "local"
+  "mutation_scope": "system"
 }

design-workflow/references/routing.md

@@ -18,19 +18,35 @@ evidence.
 
 ## Meaningful existing design
 
-Treat a design as meaningful when available evidence establishes at least two of
-the following and the user has not asked to discard them:
+`meaningful_design_exists` answers whether the evidence establishes a coherent
+design direction that must be preserved. It does not answer whether any input
+file, draft, or artifact exists.
+
+Treat a design as meaningful when the available evidence establishes a
+repeatable visual, interaction, component, or identity system, or a sufficiently
+resolved composition whose design decisions must be preserved. Relevant
+evidence includes:
 
 - content hierarchy or information architecture
 - recurring layout or spacing logic
 - typography, color, shape, imagery, or motion language
 - component and interaction patterns
 - brand identity or campaign identity
 - an approved editable artifact, implementation, template, or design contract
-
-Treat partial evidence dimension by dimension. A wireframe can fix hierarchy
-while leaving visual language open. A brand guide can fix identity while leaving
-page composition open. Record these as separate fixed and changeable fields.
+  that actually encodes design decisions
+
+Do not count a file's physical existence by itself. Treat partial evidence
+dimension by dimension. A wireframe or text plan can fix content order and
+information architecture while `meaningful_design_exists` remains `false`; in
+that case `create` establishes the visual direction without changing those fixed
+dimensions. A brand guide can establish a meaningful identity while leaving page
+composition open. Record every constraint in `fixed` and every permitted design
+dimension in `changeable`.
+
+The contract validator requires `meaningful_design_exists=false` for `create`
+and requires `true` for `preserve`, `expand`, and `redesign`. Analysis,
+translation, and documentation routes may operate on partial evidence, so their
+value follows the evidence rather than the physical presence of an artifact.
 
 ## Explicit redesign authorization