docs: polish watchlist skill guardrails

Author: dd3ok

.agents/skills/watchlist-md/SKILL.md

@@ -3,10 +3,11 @@ name: watchlist-md
 description: >-
   Manages WATCHLIST.md entries for explicit user-requested deferred checks and
   lifecycle updates. Use when the user mentions WATCHLIST.md, a WL-YYYYMMDD-NNN
-  item ID, WATCHLIST.md에 추가, watchlist로 남겨, 후속 체크로 기록, pending
-  result, or asks to record time/event-gated CI, deploy, job, data sync, order,
-  ticket, PR, or email follow-up. Do not trigger for generic reminder/scheduler
-  requests unless the user explicitly asks to record a WATCHLIST.md note.
+  item ID, WATCHLIST.md에 추가, watchlist로 남겨, 후속 체크로 기록, or asks to
+  record a pending result for later review, time/event-gated CI, deploy, job,
+  data sync, order, ticket, PR, or email follow-up. Do not trigger for generic
+  reminder/scheduler requests unless the user explicitly asks to record a
+  WATCHLIST.md note.
   Lifecycle words such as 완료, 삭제, 취소, 드롭, 차단, 연기, 보관, and 아카이브
   apply only when they clearly refer to WATCHLIST.md or a WL-YYYYMMDD-NNN item.
   Records notes only; never schedules reminders or wakeups without an explicitly
@@ -48,6 +49,10 @@ Add an item only when the user explicitly asks to record a future, time-gated, o
 event-gated check, or has opted into pre-authorized watchlist recording. If the
 task can reasonably be completed now, do that instead.
 
+Pre-authorized watchlist recording is scoped to the current repository/workspace
+and active workflow unless the user explicitly says otherwise. Do not treat it as
+global memory.
+
 Use this item shape:
 
 ```md
@@ -57,7 +62,7 @@ Use this item shape:
 - owner: user|assistant_on_review|both|external
 - due_at: YYYY-MM-DDTHH:MM:SS+09:00
 - created_at: YYYY-MM-DDTHH:MM:SS+09:00
-- source: short stable pointer, link, file, PR, issue, or conversation note
+- source: short stable pointer, safe link, file, PR, issue, or conversation note
 - trigger: why this needs a later check
 - action: what to check or do
 - done_when: observable success condition
@@ -66,22 +71,27 @@ Use this item shape:
 - next_step_on_fail:
 ```
 
-Required information: ID, status, due time, owner, action, done condition, and
-source/context. Use `assistant_on_review` when the assistant should help on the
-next explicit review. Treat legacy `owner: agent` as `assistant_on_review`.
+Required information for open items: ID, status, priority, owner, due_at value,
+created_at, source, trigger, action, and done_when. Recommended when known:
+next_step_on_fail. Normally blank until checked: last_checked_at and result. Do
+not store signed, tokenized, private, or credential-bearing links. Use
+`assistant_on_review` when the assistant should help on the next explicit review.
+Treat legacy `owner: agent` as `assistant_on_review`.
 
-Generate IDs as `WL-YYYYMMDD-NNN` from the creation date in Asia/Seoul unless the
-file or user specifies another timezone. Before writing, re-read WATCHLIST.md and
-choose the next unused sequence for that date. Never overwrite an existing item.
+Generate IDs as `WL-YYYYMMDD-NNN` from the creation date in the WATCHLIST
+timezone. Prefer the WATCHLIST.md `timezone:` field, then explicit user timezone,
+then environment/user timezone; if none is available, use Asia/Seoul. Before
+writing, re-read WATCHLIST.md and choose the next unused sequence for that date.
+Never overwrite an existing item.
 
 Convert relative times to absolute ISO-8601 timestamps with timezone when possible.
 If time is ambiguous, use `due_at: unscheduled` and mention the ambiguity. If the
 resolved time is already in the past, ask whether to record it or use the next
 occurrence; if clarification is unavailable, use `unscheduled`.
 
-After adding, confirm the item ID, due time, action, done condition, and scheduler
-status. If no scheduler was used, say `scheduler: none` and avoid promising future
-execution.
+After adding, confirm the item ID, due_at value, action, done_when, and scheduler
+status. If no scheduler was used, say `scheduler: none` and avoid promising
+future execution.
 
 ## Review
 

.agents/skills/watchlist-md/references/lifecycle.md

@@ -76,8 +76,9 @@ Git history cleanup separately; do not rewrite history unless explicitly asked.
 
 ## ID And Time Rules
 
-- Generate IDs as `WL-YYYYMMDD-NNN` from the creation date in Asia/Seoul by
-  default.
+- Generate IDs as `WL-YYYYMMDD-NNN` from the creation date in the WATCHLIST
+  timezone. Prefer the WATCHLIST.md `timezone:` field, then explicit user
+  timezone, then environment/user timezone; if none is available, use Asia/Seoul.
 - Use the next `NNN` for that date by reading existing item IDs.
 - Immediately before writing, re-read WATCHLIST.md and scan all existing IDs. If
   the chosen ID already exists, increment `NNN` until an unused ID is found.

README.ko.md

@@ -200,6 +200,8 @@ python3 evals/check_semantic_cases.py
 
 `evals/prompts.csv`, `evals/rubric.md`, `evals/self_checks.yaml`, `evals/cases/*.json`은 수동 또는 자동 에이전트 평가에 사용할 작은 프롬프트 회귀 세트입니다. Semantic case checker는 기대 trigger와 operation 계약을 검증하며, LLM 또는 agent를 실행하지 않습니다.
 
+`--strict-safety`는 의도적으로 보수적입니다. 공유/팀 템플릿에서는 signed URL 또는 tokenized URL처럼 보이는 휴리스틱 결과도 error로 올립니다. false positive는 검토하고, 민감한 링크를 WATCHLIST.md에 복사하기보다 safe pointer를 선호하세요.
+
 ## Example Item
 
 ```md
@@ -220,6 +222,8 @@ python3 evals/check_semantic_cases.py
 
 `owner`는 다음 명시적인 WATCHLIST 검토 중에 누가 조치해야 하는지를 의미합니다. 이는 어시스턴트가 자동으로 깨어난다는 의미는 아닙니다.
 
+검증기는 모든 필드 키를 요구합니다. 키는 위의 안정적인 순서대로 있어야 하지만, open 항목에서 모든 필드 값이 채워져야 하는 것은 아닙니다. open 항목의 필수 값은 `status`, `priority`, `owner`, `due_at`, `created_at`, `source`, `trigger`, `action`, `done_when`입니다. 알 수 있으면 권장되는 값은 `next_step_on_fail`입니다. 확인 전에는 보통 비워 둡니다: `last_checked_at`, `result`.
+
 완료 처리의 기본 동작은 `status: done`, `last_checked_at`, `result`를 채우고, `## Done` 섹션이 있으면 완료 항목을 그 아래로 이동하는 것입니다. 사용자가 “상태만 바꿔” 또는 “위치 유지”처럼 명시하면 항목을 원래 위치에 둘 수 있습니다.
 
 `dropped`는 더 이상 필요 없는 후속 확인의 기록을 보존하는 상태입니다. Delete는 기록 자체를 제거하는 동작이므로 기본적으로 권장하지 않으며, 사용자가 명시적으로 삭제를 요청할 때만 수행해야 합니다.

README.md

@@ -200,6 +200,8 @@ python3 evals/check_semantic_cases.py
 
 `evals/prompts.csv`, `evals/rubric.md`, `evals/self_checks.yaml`, and `evals/cases/*.json` are a small prompt regression set for manual or automated agent evaluation. The semantic case checker validates the expected trigger and operation contract; it does not run an LLM or agent.
 
+`--strict-safety` is intentionally conservative. It escalates heuristic findings such as signed or tokenized-looking URLs to errors for shared/team templates; review false positives and prefer safe pointers instead of copying sensitive links into WATCHLIST.md.
+
 ## Example Item
 
 ```md
@@ -220,6 +222,8 @@ python3 evals/check_semantic_cases.py
 
 `owner` means who should act during the next explicit WATCHLIST review. It does not mean the assistant will wake up automatically.
 
+The validator requires every field key in the stable order shown above, but not every field needs a populated value for an open item. Required values for open items are `status`, `priority`, `owner`, `due_at`, `created_at`, `source`, `trigger`, `action`, and `done_when`. Recommended when known: `next_step_on_fail`. Normally blank until checked: `last_checked_at` and `result`.
+
 By default, completing an item sets `status: done`, fills `last_checked_at` and `result`, and moves the item under `## Done` when that section exists. If the user explicitly says to change only the status or keep the item in place, leave the item in its original section.
 
 `dropped` preserves a record for a follow-up that is no longer needed. Delete removes the record itself, so it is not the default and should only be used when the user explicitly asks to delete the record.

evals/check_policy_markers.py

@@ -14,6 +14,8 @@
         "Concurrent Edits",
         "Do not store passwords, tokens",
         "untrusted",
+        "`--strict-safety` is intentionally conservative",
+        "Required values for open items",
     ],
     "README.ko.md": [
         "Deletion And Retention Policy",
@@ -23,6 +25,8 @@
         "Concurrent Edits",
         "비밀번호, 토큰",
         "신뢰할 수 없는",
+        "`--strict-safety`는 의도적으로 보수적입니다",
+        "open 항목의 필수 값",
     ],
     ".agents/skills/watchlist-md/SKILL.md": [
         "Lifecycle words such as",
@@ -32,13 +36,22 @@
         "untrusted data",
         "references/lifecycle.md",
         "references/safety.md",
+        "pending result for later review",
+        "safe link",
+        "Pre-authorized watchlist recording is scoped",
+        "Required information for open items",
+        "due_at value",
+        "WATCHLIST.md `timezone:` field",
+        "environment/user timezone",
     ],
     ".agents/skills/watchlist-md/references/lifecycle.md": [
         "Deletion And Retention Policy",
         "Do not archive items automatically",
         "Archive Policy",
         "Concurrent Edit And ID Collision Policy",
         "List-only reviews must not mutate",
+        "WATCHLIST.md `timezone:` field",
+        "environment/user timezone",
     ],
     ".agents/skills/watchlist-md/references/safety.md": [
         "Do not store secrets",

evals/test_check_watchlist.py

@@ -581,6 +581,57 @@ def test_skill_runtime_guidance_stays_lean(self):
         self.assertIn("references/safety.md", text)
         self.assertLess(text.index("## Add"), text.index("references/lifecycle.md"))
 
+    def test_skill_runtime_polish_markers_stay_precise(self):
+        text = (SKILL_DIR / "SKILL.md").read_text(encoding="utf-8")
+        lifecycle = (SKILL_DIR / "references" / "lifecycle.md").read_text(encoding="utf-8")
+        normalized_text = " ".join(text.split()).lower()
+        normalized_lifecycle = " ".join(lifecycle.split())
+        timezone_precedence = (
+            "Prefer the WATCHLIST.md `timezone:` field, then explicit user timezone, "
+            "then environment/user timezone; if none is available, use Asia/Seoul."
+        )
+        required_information = (
+            "Required information for open items: ID, status, priority, owner, "
+            "due_at value, created_at, source, trigger, action, and done_when."
+        )
+
+        self.assertIn("pending result for later review", text)
+        self.assertNotIn("후속 체크로 기록, pending", text)
+        self.assertIn(
+            "pre-authorized watchlist recording is scoped to the current repository/workspace",
+            normalized_text,
+        )
+        self.assertIn(
+            "- source: short stable pointer, safe link, file, PR, issue, or conversation note",
+            text,
+        )
+        self.assertIn("due_at value", text)
+        self.assertNotIn("due time", text)
+        self.assertIn(required_information, " ".join(text.split()))
+        self.assertNotIn("done condition", text)
+        self.assertIn("action, done_when, and scheduler status", " ".join(text.split()))
+        self.assertIn("watchlist timezone", normalized_text)
+        self.assertIn("environment/user timezone", normalized_text)
+        self.assertIn(timezone_precedence, " ".join(text.split()))
+        self.assertIn(timezone_precedence, normalized_lifecycle)
+
+    def test_readme_documents_field_and_strict_safety_expectations(self):
+        english = (REPO_ROOT / "README.md").read_text(encoding="utf-8")
+        korean = (REPO_ROOT / "README.ko.md").read_text(encoding="utf-8")
+
+        self.assertIn("The validator requires every field key", english)
+        self.assertIn("Required values for open items", english)
+        self.assertIn("`source`, `trigger`, `action`, and `done_when`", english)
+        self.assertIn("Recommended when known", english)
+        self.assertIn("Normally blank until checked", english)
+        self.assertIn("`--strict-safety` is intentionally conservative", english)
+        self.assertIn("검증기는 모든 필드 키를 요구합니다", korean)
+        self.assertIn("open 항목의 필수 값", korean)
+        self.assertIn("`source`, `trigger`, `action`, `done_when`", korean)
+        self.assertIn("알 수 있으면 권장되는 값", korean)
+        self.assertIn("확인 전에는 보통 비워 둡니다", korean)
+        self.assertIn("`--strict-safety`는 의도적으로 보수적입니다", korean)
+
     def test_starter_templates_label_commented_item_as_example_only(self):
         paths = [
             SKILL_DIR / "assets" / "WATCHLIST.template.md",