lee-spec-kit 0.9.14 → 0.9.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.9.14",
+  "version": "0.9.16",
   "description": "Document-centered harness engineering toolkit for AI agent development",
   "type": "module",
   "bin": {
@@ -15,18 +15,6 @@
     "resources",
     "THIRD_PARTY_NOTICES.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "eslint src",
-    "lint:test": "eslint tests",
-    "typecheck": "tsc --noEmit",
-    "typecheck:test": "tsc -p tsconfig.tests.json --noEmit",
-    "test": "pnpm build && vitest run",
-    "test:race": "pnpm build && vitest run tests/race.test.mjs",
-    "format": "prettier --write .",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "docs",
     "template",
@@ -68,5 +56,15 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "packageManager": "pnpm@10.7.0"
-}
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "lint:test": "eslint tests",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.tests.json --noEmit",
+    "test": "pnpm build && vitest run",
+    "test:race": "pnpm build && vitest run tests/race.test.mjs",
+    "format": "prettier --write ."
+  }
+}

package/templates/en/common/agents/agents.md

@@ -49,6 +49,16 @@ This document defines workflow policy, not a custom runtime loop.
 - Do not use `docs/designs/` for system architecture, data/API design, technical research, or implementation plans.
 - Follow the detailed routing rules in `docs/README.md`.
 
+## README protection and Feature supporting artifacts
+
+- Modify an existing README (including root, nested, and localized variants) only when the user explicitly requests README changes, and only within that scope. Generic implementation or documentation-sync requests and agent-authored Plans do not authorize README edits. Reading and referencing remain allowed.
+- When README editing is requested, update the relevant existing explanation; do not continually append feature implementation details, verification logs, or version-by-version change notes.
+- README protection takes precedence over documentation sync and Curated Documentation Impact. Without a README edit request, record a discovered discrepancy's path, evidence, and deferral reason in `decisions.md`. Assess other documentation changes independently. Use `NONE` for a surface with only this deferred README impact to mean no edit in this change, with a reference to that record; do not claim the discrepancy is absent or resolved. For this exception only, do not require a separate follow-up task/Feature/issue or README edit approval to complete the work. Reviewers must not block solely because the README remains unchanged.
+- Store retained Feature supporting artifacts (explanatory diagrams, verification reports, screenshots) in `artifacts/` beside the active Feature's `spec.md`, `plan.md`, `tasks.md`, and `decisions.md`. Create the directory only when needed and link files relatively from `tasks.md` or `decisions.md`. Do not create separate reports that duplicate sufficient existing documentation.
+- Resolve the actual active Feature docs path: in standalone mode this is inside its docs worktree. Never guess from the current working directory or the most recent Feature. Implementation workers retain their no-docs-write contract and hand necessary artifacts to the primary agent for storage.
+- Explicit user destinations and tool-required output locations take precedence. Product code/assets use project paths; build output, caches, and disposable debugging files use existing output or temporary locations; shared authoritative docs follow existing routing. OpenWiki publications and receipts retain their Knowledge storage policy. Without an active Feature, use existing documentation or temporary storage rather than inventing or selecting a Feature.
+- Do not create arbitrary root-level `reports/`, `screenshots/`, or `artifacts/` instead of the default destination. Include only necessary, committable artifacts in the Feature; exclude secrets and temporary large outputs.
+
 ## Knowledge Architecture
 
 - Product intent and durable requirements belong to PRD; an active Feature links and narrows them, and requirement changes must be backfilled to PRD.
@@ -59,6 +69,15 @@ This document defines workflow policy, not a custom runtime loop.
 - `experimental.openwiki=true` publishes Knowledge after integration: local workflows run the returned `knowledge publish` action after verified merge and before cleanup; GitHub workflows use the post-push CI created by `knowledge ci`. Missing or false disables this lifecycle.
 - Generate in an isolated worktree and publish revision-bound artifacts outside the source branch. Do not add generated Wiki or receipts to Feature commits or Feature review required documents. Keep curated PRD/architecture updates in the Feature.
 
+### Knowledge publication diagnostics and recovery
+
+- `knowledge publish --json` emits one final JSON object on stdout and stage, attempt, observed runId, page progress, elapsed time, and retry reason on stderr. Use `knowledge status --component <name> --json` to inspect the current attempt and the last good publication.
+- Total and no-output timeouts are disabled by default. An explicit `--absolute-timeout-ms` covers preparation, generation, verification, and automatic retries in one invocation; `--idle-timeout-ms` is also opt-in. A slow page alone does not prove a stalled provider. No new retry or publication proceeds after an explicit budget is exhausted. Manual resume starts a new invocation while retaining prior elapsed time and diagnostics.
+- Evidence failures receive one targeted page and Claims repair only when the diagnostics fit a complete bounded request, followed by full validation. Unknown repair scope or failed revalidation stops the run; it never escalates automatically to full regeneration. Full reset is reserved for a changed receipt writing policy that requires every page to be rewritten.
+- Preserve generated output before repair or reset. Per-execution diagnostics remain in the shared Git runtime at `knowledge-executions/<id>/events.jsonl`; follow `diagnosticsPath` and `snapshotPath`. Never log raw prompts, provider output, or credentials. Snapshots contain existing OpenWiki files, so inspect them before sharing externally.
+- SIGINT and SIGTERM produce an interrupted state. Status resolves abandoned `running` records using PID and lock ownership after uncatchable termination such as SIGKILL. Legacy ownership that cannot be proven is `unknown`, not assumed running.
+- Failures preserve the integrated commit and last good publication. A saved queue for the same Feature, component, and integration resumes in its worktree only after owner, writing policy, and completed page/Claims/manifest checks. Mismatches are preserved and blocked. New integrations start from the verified last publication artifact. Follow workflow-stage into cleanup only after publication succeeds; do not automatically repeat verification or merge.
+
 ## Optional UI/UX Design Policy
 
 - Only when the user request explicitly mentions a design system, UI/visual redesign, design consistency, shared UI/component-library consolidation, branding/theme/token redesign, or implementation from Figma/design images, read and apply `npx lee-spec-kit docs get ui-ux-design --json`.
@@ -106,3 +125,5 @@ This document defines workflow policy, not a custom runtime loop.
 - Replies: English unless project policy overrides it
 - Code and filenames: English
 - Dates and times: use the user's local system time
+
+When chaining audit and commit in a shell, use `commit-audit --json --enforce`. With `--json` alone, inspect the JSON status: a blocked audit can exit zero. Changes limited to lee-spec-kit managed rules and tooling configuration are not Knowledge output changes.

package/templates/en/common/agents/skills/create-pr.md

@@ -17,6 +17,8 @@ Execution-state SSOT is the feature-local `pr.md`.
 
 ## Pre-PR Baseline Checklist (`builtin-checklist`)
 
+Apply the README protection and supporting-artifact rules in the `agents` document first. Without an explicit README edit request, a README discrepancy may use `NONE` referencing its path, evidence, and deferral reason in `decisions.md`; this exception requires no separate follow-up item or edit approval. Store retained Feature supporting artifacts in the active Feature’s `artifacts/` and link them relatively.
+
 The Pre-PR subagent must always run this minimum baseline. Do not depend on a named review skill.
 
 Review Curated Documentation Impact evidence, including NONE. For each discovered discrepancy, verify a completed correction or a real follow-up task/Feature/issue with document paths, evidence, the unresolved question, and the deferral reason. A residual-risk note alone is not follow-up tracking. Report missing disposition as a finding; do not infer product intent from code or generated Knowledge. Existing review-round and approval policies still apply.
@@ -95,7 +97,7 @@ Include the artifacts in the PR body.
 - Default is `pr.screenshots.upload: false`. If you need upload/URL inclusion, enable it in `.lee-spec-kit.json`.
 - If `.lee-spec-kit.json` has `pr.screenshots.upload: false`, **do not upload/include URLs**, and **do not include a "Screenshots" section** in the PR body.
 - Use `agent-browser` to generate screenshots.
-- Save files under a local temp folder (`/tmp/lee-spec-kit/pr-assets/`).
+- Save retained screenshots in the active Feature’s `artifacts/screenshots/`. Set `FEATURE_DOC_DIR` below to the absolute path of the actual active Feature docs directory.
 - Upload them as Release assets, then put the image URLs into the "Screenshots" section of the PR body.
 - Before uploading, **open the image file** and verify, then ask the user to validate before PR creation:
   - It is not a login/permission/error/blank page
@@ -121,15 +123,17 @@ DEV_PID=$!
 PREVIEW_URL=\"http://127.0.0.1:${PORT}\"
 
 # (example) capture from a preview URL
-mkdir -p /tmp/lee-spec-kit/pr-assets
+FEATURE_DOC_DIR="/absolute/path/to/active-feature"
+PR_ASSET_DIR="$FEATURE_DOC_DIR/artifacts/screenshots"
+mkdir -p "$PR_ASSET_DIR"
 agent-browser open "$PREVIEW_URL"
-agent-browser screenshot /tmp/lee-spec-kit/pr-assets/ui-1.png --full
+agent-browser screenshot "$PR_ASSET_DIR/ui-1.png" --full
 agent-browser close
 
 # (required) open and validate the screenshot (re-capture if login/error/blank)
-ls -lh /tmp/lee-spec-kit/pr-assets/ui-1.png
-# macOS: open /tmp/lee-spec-kit/pr-assets/ui-1.png
-# Linux: xdg-open /tmp/lee-spec-kit/pr-assets/ui-1.png
+ls -lh "$PR_ASSET_DIR/ui-1.png"
+# macOS: open "$PR_ASSET_DIR/ui-1.png"
+# Linux: xdg-open "$PR_ASSET_DIR/ui-1.png"
 
 # (recommended) stop the dev server you started for screenshots
 kill \"$DEV_PID\" >/dev/null 2>&1 || true
@@ -145,7 +149,7 @@ TAG="pr-assets/${SAFE_BRANCH}"
 gh release view "$TAG" >/dev/null 2>&1 || \
   gh release create "$TAG" --prerelease --title "pr-assets: ${SAFE_BRANCH}" --notes ""
 
-gh release upload "$TAG" /tmp/lee-spec-kit/pr-assets/* --clobber
+gh release upload "$TAG" "$PR_ASSET_DIR"/* --clobber
 
 echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 ```

package/templates/en/common/agents/skills/execute-task.md

@@ -34,6 +34,8 @@ Use the active feature folder as the execution SSOT.
 
 ## 3. Keep docs in sync
 
+Apply the README protection and supporting-artifact rules in the `agents` document first. Without an explicit README edit request, a README discrepancy may use `NONE` referencing its path, evidence, and deferral reason in `decisions.md`; this exception requires no separate follow-up item or edit approval. Store retained Feature supporting artifacts in the active Feature’s `artifacts/` and link them relatively.
+
 Do not close a discovered documentation discrepancy with a decisions.md note alone. For an unambiguous factual error within approved scope, declare UPDATE/ADD and link a task Docs target. If product intent or scope expansion needs confirmation, record the conflicting document paths and evidence, the question to resolve, the deferral reason, and a real follow-up task/Feature/issue reference. Never invent identifiers or approvals. If creating the tracking item needs approval, do not report resolution before user confirmation. Explain in NONE evidence whether no known discrepancy remains or a remaining discrepancy is tracked by that follow-up. Never delete unimplemented PRD requirements merely to match code or OpenWiki.
 
 - `spec.md`: update when user-visible scope or acceptance criteria change

package/templates/en/common/features/feature-base/plan.md

@@ -51,6 +51,8 @@ src/
 
 ## Curated Documentation Impact
 
+Apply the README protection and supporting-artifact rules in the `agents` document first. Without an explicit README edit request, a README discrepancy may use `NONE` referencing its path, evidence, and deferral reason in `decisions.md`; this exception requires no separate follow-up item or edit approval. Store retained Feature supporting artifacts in the active Feature’s `artifacts/` and link them relatively.
+
 Do not close a discovered documentation discrepancy with a decisions.md note alone. For an unambiguous factual error within approved scope, declare UPDATE/ADD and link a task Docs target. If product intent or scope expansion needs confirmation, record the conflicting document paths and evidence, the question to resolve, the deferral reason, and a real follow-up task/Feature/issue reference. Never invent identifiers or approvals. If creating the tracking item needs approval, do not report resolution before user confirmation. Explain in NONE evidence whether no known discrepancy remains or a remaining discrepancy is tracked by that follow-up. Never delete unimplemented PRD requirements merely to match code or OpenWiki.
 
 > Complete this assessment even when every decision is `NONE`. `NONE` means the surface was reviewed and no human-owned project document needs to change. Generated OpenWiki synchronization is evaluated separately.

package/templates/ko/common/agents/agents.md

@@ -49,6 +49,16 @@
 - `docs/designs/`를 시스템 아키텍처, 데이터/API 설계, 기술 조사, 구현 계획의 목적지로 사용하지 않습니다.
 - 세부 설명은 `docs/README.md`의 문서 라우팅 규칙을 따릅니다.
 
+## README 보호와 Feature 보조 산출물
+
+- 기존 README(루트·하위 디렉터리·다국어 포함)는 사용자가 README 수정을 명시적으로 요청한 경우에만 요청 범위에서 수정합니다. 일반적인 기능 구현·문서 동기화 요청이나 에이전트가 작성한 Plan은 README 수정 허가가 아닙니다. 읽기와 참조는 허용합니다.
+- README 수정 요청이 있어도 관련 기존 설명을 갱신하며, 기능별 구현 내역·검증 로그·버전별 변경 설명을 끝에 계속 덧붙이지 않습니다.
+- README 보호는 문서 동기화와 Curated Documentation Impact 규칙보다 우선합니다. 수정 요청 없이 발견한 README 불일치는 `decisions.md`에 경로·근거·보류 사유를 기록합니다. 다른 문서 영향은 별도로 판정합니다. 해당 영역에 보류된 README 영향만 있으면 이번 작업에서 수정하지 않는다는 `NONE`과 해당 기록 참조를 사용하며, 불일치가 없거나 해결됐다고 주장하지 않습니다. 이 경우에만 별도 후속 task/Feature/issue 생성이나 README 수정 승인을 완료 조건으로 요구하지 않습니다. 리뷰도 README 미수정 자체를 차단 사유로 삼지 않습니다.
+- 보존할 Feature 보조 산출물(설명용 다이어그램·검증 보고서·스크린샷)은 활성 Feature의 `spec.md`, `plan.md`, `tasks.md`, `decisions.md`와 같은 디렉터리 아래 `artifacts/`에 저장합니다. 필요할 때만 폴더를 만들고 `tasks.md` 또는 `decisions.md`에서 상대경로로 연결합니다. 기존 문서로 충분한 내용을 별도 보고서로 중복 생성하지 않습니다.
+- 활성 Feature 문서의 실제 경로를 사용합니다. standalone에서는 해당 docs worktree 안의 Feature 경로이며, 현재 작업 디렉터리나 최근 Feature로 추측하지 않습니다. 구현 worker는 docs 쓰기 금지 계약을 유지하고 필요한 산출물을 메인 에이전트에 전달하여 저장하도록 합니다.
+- 사용자 지정 경로와 도구가 요구하는 출력 경로를 우선합니다. 제품 코드·제품 자산은 프로젝트 경로, 빌드·캐시·일회성 디버깅 파일은 기존 출력 경로나 임시 디렉터리, 공유 정식 문서는 기존 문서 정책을 따릅니다. OpenWiki 게시물·receipt는 기존 Knowledge 저장 규칙을 유지합니다. 활성 Feature가 없으면 임의 Feature를 만들거나 선택하지 말고 기존 문서 또는 임시 경로를 사용합니다.
+- 기본 위치 대신 루트나 임의의 `reports/`, `screenshots/`, `artifacts/`를 만들지 않습니다. 보존할 필요가 있고 커밋 가능한 산출물만 Feature에 포함하며 비밀정보·임시 대용량 출력을 넣지 않습니다.
+
 ## Knowledge Architecture
 
 - 제품 의도와 장기 요구사항의 기준은 PRD입니다. 활성 Feature는 이를 연결하고 구체화하며, 요구사항 변경은 PRD에 다시 반영해야 합니다.
@@ -59,6 +69,15 @@
 - `experimental.openwiki=true`이면 통합 후 Knowledge를 게시합니다. local은 머지 검증 후 cleanup 전에 반환된 `knowledge publish`를 실행하고, GitHub는 `knowledge ci`로 준비한 기준 브랜치 push CI에서 실행합니다. 누락 또는 false이면 이 흐름을 사용하지 않습니다.
 - 별도 worktree에서 생성하고 코드 revision별 artifact로 저장합니다. 생성 Wiki와 receipt를 Feature 커밋이나 Feature 리뷰 필수 문서에 추가하지 않습니다. PRD·아키텍처 등 사람이 관리하는 문서는 Feature에서 함께 수정합니다.
 
+### Knowledge 게시 진단과 복구
+
+- `knowledge publish --json`은 stdout에 최종 JSON 하나를 반환하며 stderr에 단계·실행 차수·runId(관찰된 경우)·페이지 진행·경과 시간·재시도 이유를 출력합니다. `knowledge status --component <name> --json`으로 현재 게시 상태와 마지막 정상 게시본을 확인합니다.
+- 총 시간 제한과 무출력 시간 제한은 기본으로 꺼져 있습니다. `--absolute-timeout-ms`를 명시하면 준비·생성·검증·자동 재시도를 합친 한 번의 호출에 적용합니다. `--idle-timeout-ms`도 명시할 때만 적용하며, 페이지가 오래 걸리는 것만으로 정체라고 단정하지 않습니다. 명시한 예산 초과 후 새 재시도나 게시를 진행하지 않습니다. 수동 재개는 새 호출이며 이전 실행 시간과 진단 경로는 보존합니다.
+- evidence 오류는 진단 범위가 한 번의 제한된 수정 요청에 담길 때만 해당 페이지·Claims를 부분 수정한 뒤 전체 검증합니다. 복구 범위가 불명확하거나 재검증이 실패하면 중단하며, 자동 전체 재생성으로 전환하지 않습니다. 기존 receipt의 글쓰기 정책이 바뀌어 모든 페이지를 다시 작성해야 하는 경우에만 전체 초기화를 수행합니다.
+- 수정/초기화 전 기존 생성물을 보존하고, 실행별 진단은 Git 공용 runtime의 `knowledge-executions/<id>/events.jsonl`에 남깁니다. `diagnosticsPath`와 `snapshotPath`를 사용하며 원문 프롬프트·provider 출력·인증정보를 별도 로그에 기록하지 않습니다. 보존 사본은 기존 OpenWiki 파일이므로 외부 공유 전 내용을 확인합니다.
+- SIGINT/SIGTERM은 중단 상태로 종료합니다. SIGKILL 등으로 남은 `running`은 상태 조회 시 PID와 잠금 소유권으로 재판정합니다. 구형 기록의 소유권을 확인할 수 없으면 `unknown`으로 표시하며 실행 중이라고 단정하지 않습니다.
+- 실패해도 통합 커밋과 마지막 정상 게시본은 유지합니다. 같은 Feature/component와 통합 커밋의 저장된 page queue가 있으면 owner·작성 정책·완료 페이지와 Claims/manifest 해시를 먼저 검사한 뒤 기존 worktree에서 이어갑니다. 불일치는 보존 후 차단합니다. 새 통합 커밋의 갱신은 검증한 최근 정상 게시 artifact를 기준으로 시작합니다. 게시 성공 후 workflow-stage의 cleanup을 따르며 통합 검증과 병합을 무조건 반복하지 않습니다.
+
 ## 선택적 UI/UX 디자인 정책
 
 - 사용자 요청에 design system, UI/visual redesign, 디자인 일관성, 공통 UI/component library 정리, branding/theme/token 재설계, Figma/디자인 이미지 기반 구현이 명시된 경우에만 `npx lee-spec-kit docs get ui-ux-design --json`을 읽고 적용합니다.
@@ -108,3 +127,5 @@
 - 답변: 한국어
 - 코드/파일명: 영어
 - 날짜/시간: 사용자 로컬 시스템 시간
+
+셸에서 감사와 커밋을 연결할 때는 `commit-audit --json --enforce`를 사용합니다. `--json`만 사용하면 `status: blocked`여도 종료코드는 0일 수 있으므로 JSON 상태를 확인해야 합니다. lee-spec-kit 관리 블록과 도구 설정 변경은 OpenWiki 생성물 변경으로 분류하지 않습니다.

package/templates/ko/common/agents/skills/create-pr.md

@@ -17,6 +17,8 @@ Pull Request를 생성할 때 따르는 가이드입니다.
 
 ## Pre-PR 기본 체크리스트(`builtin-checklist`)
 
+README 보호와 보조 산출물 위치는 `agents` 문서의 해당 규칙을 우선합니다. README 불일치는 수정 요청이 없으면 `decisions.md`의 경로·근거·보류 사유를 참조하는 `NONE`으로 기록할 수 있으며, 이 예외에 별도 후속 항목이나 수정 승인을 요구하지 않습니다. 보존할 Feature 보조 산출물은 활성 Feature의 `artifacts/`에 저장하고 상대경로로 연결합니다.
+
 Pre-PR 리뷰에서 서브에이전트가 항상 수행하는 최소 기준입니다. 리뷰 스킬 이름에 의존하지 않습니다.
 
 Curated Documentation Impact의 NONE을 포함한 근거를 검토합니다. 발견한 불일치마다 수정 완료 또는 실제 후속 task/Feature/issue 연결을 확인하고 문서 경로·근거·미해결 질문·보류 이유를 점검합니다. 잔여 위험 문구만으로는 후속 추적이 아닙니다. 처리 누락은 finding으로 보고하며 코드나 파생 Knowledge로 제품 의도를 추정하지 않습니다. 기존 리뷰 횟수와 승인 정책은 그대로 적용합니다.
@@ -95,7 +97,7 @@ PR 본문에 결과물을 포함합니다.
 - 기본값은 `pr.screenshots.upload: false`입니다. 업로드/URL 포함이 필요하다면 `.lee-spec-kit.json`에서 `true`로 켜세요.
 - `.lee-spec-kit.json`에서 `pr.screenshots.upload: false`라면 **업로드/URL 포함을 하지 않으며**, PR 본문에서도 **"스크린샷" 섹션을 만들지 않습니다.**
 - `agent-browser`로 스크린샷을 생성합니다.
-- 스크린샷 파일은 로컬 임시 폴더(`/tmp/lee-spec-kit/pr-assets/`)에 저장합니다.
+- 보존할 스크린샷은 활성 Feature의 `artifacts/screenshots/`에 저장합니다. 아래 `FEATURE_DOC_DIR`에는 실제 활성 Feature 문서 디렉터리의 절대경로를 지정합니다.
 - 릴리스 자산(Release assets)으로 업로드한 뒤, 생성된 이미지 URL을 PR 본문 "스크린샷" 섹션에 넣습니다.
 - 스크린샷을 업로드하기 전에 **이미지 파일을 직접 열어** 다음을 확인하고, PR 생성 전 사용자에게도 검증받습니다.
   - 로그인 화면/권한 오류/에러 화면/빈 화면이 아닌지
@@ -121,15 +123,17 @@ DEV_PID=$!
 PREVIEW_URL=\"http://127.0.0.1:${PORT}\"
 
 # (예시) 미리보기 URL을 정해 스크린샷 생성
-mkdir -p /tmp/lee-spec-kit/pr-assets
+FEATURE_DOC_DIR="/absolute/path/to/active-feature"
+PR_ASSET_DIR="$FEATURE_DOC_DIR/artifacts/screenshots"
+mkdir -p "$PR_ASSET_DIR"
 agent-browser open "$PREVIEW_URL"
-agent-browser screenshot /tmp/lee-spec-kit/pr-assets/ui-1.png --full
+agent-browser screenshot "$PR_ASSET_DIR/ui-1.png" --full
 agent-browser close
 
 # (필수) 스크린샷 파일을 열어 검증 (로그인/에러/빈 화면이면 재촬영)
-ls -lh /tmp/lee-spec-kit/pr-assets/ui-1.png
-# macOS: open /tmp/lee-spec-kit/pr-assets/ui-1.png
-# Linux: xdg-open /tmp/lee-spec-kit/pr-assets/ui-1.png
+ls -lh "$PR_ASSET_DIR/ui-1.png"
+# macOS: open "$PR_ASSET_DIR/ui-1.png"
+# Linux: xdg-open "$PR_ASSET_DIR/ui-1.png"
 
 # (권장) 스크린샷을 위해 띄운 개발 서버는 작업이 끝나면 종료합니다.
 kill \"$DEV_PID\" >/dev/null 2>&1 || true
@@ -145,7 +149,7 @@ TAG="pr-assets/${SAFE_BRANCH}"
 gh release view "$TAG" >/dev/null 2>&1 || \
   gh release create "$TAG" --prerelease --title "pr-assets: ${SAFE_BRANCH}" --notes ""
 
-gh release upload "$TAG" /tmp/lee-spec-kit/pr-assets/* --clobber
+gh release upload "$TAG" "$PR_ASSET_DIR"/* --clobber
 
 echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 ```

package/templates/ko/common/agents/skills/execute-task.md

@@ -34,6 +34,8 @@
 
 ## 3. 문서 동기화
 
+README 보호와 보조 산출물 위치는 `agents` 문서의 해당 규칙을 우선합니다. README 불일치는 수정 요청이 없으면 `decisions.md`의 경로·근거·보류 사유를 참조하는 `NONE`으로 기록할 수 있으며, 이 예외에 별도 후속 항목이나 수정 승인을 요구하지 않습니다. 보존할 Feature 보조 산출물은 활성 Feature의 `artifacts/`에 저장하고 상대경로로 연결합니다.
+
 발견한 문서 불일치는 `decisions.md`에만 남기고 종료하지 않습니다. 현재 사실의 명백한 오류가 승인 범위 안에 있으면 `UPDATE`/`ADD`와 task `Docs`로 연결합니다. 제품 의도 확인이나 범위 확장이 필요하면 충돌한 문서 경로·근거, 확인할 질문, 보류 이유와 실제 후속 task/Feature/issue 참조를 기록합니다. 없는 번호나 승인을 만들지 않습니다. 추적 항목 생성에 승인이 필요하면 사용자 확인 전 해결된 것으로 기록하지 않습니다. `NONE`의 근거에는 알려진 불일치가 없거나, 남은 불일치가 해당 후속 항목으로 추적되고 있음을 설명합니다. 코드나 OpenWiki에 맞추기 위해 미구현 PRD 요구를 삭제하지 않습니다.
 
 - `spec.md`: 사용자-visible scope 또는 acceptance criteria가 바뀌면 갱신합니다

package/templates/ko/common/features/feature-base/plan.md

@@ -51,6 +51,8 @@ src/
 
 ## Curated Documentation Impact
 
+README 보호와 보조 산출물 위치는 `agents` 문서의 해당 규칙을 우선합니다. README 불일치는 수정 요청이 없으면 `decisions.md`의 경로·근거·보류 사유를 참조하는 `NONE`으로 기록할 수 있으며, 이 예외에 별도 후속 항목이나 수정 승인을 요구하지 않습니다. 보존할 Feature 보조 산출물은 활성 Feature의 `artifacts/`에 저장하고 상대경로로 연결합니다.
+
 발견한 문서 불일치는 `decisions.md`에만 남기고 종료하지 않습니다. 현재 사실의 명백한 오류가 승인 범위 안에 있으면 `UPDATE`/`ADD`와 task `Docs`로 연결합니다. 제품 의도 확인이나 범위 확장이 필요하면 충돌한 문서 경로·근거, 확인할 질문, 보류 이유와 실제 후속 task/Feature/issue 참조를 기록합니다. 없는 번호나 승인을 만들지 않습니다. 추적 항목 생성에 승인이 필요하면 사용자 확인 전 해결된 것으로 기록하지 않습니다. `NONE`의 근거에는 알려진 불일치가 없거나, 남은 불일치가 해당 후속 항목으로 추적되고 있음을 설명합니다. 코드나 OpenWiki에 맞추기 위해 미구현 PRD 요구를 삭제하지 않습니다.
 
 > 모든 결정이 `NONE`이어도 영향 판정을 완료합니다. `NONE`은 사람이 관리하는 상위 문서를 검토했지만 변경할 필요가 없다는 뜻입니다. 생성형 OpenWiki 동기화는 별도로 판정합니다.