feat: add archive policy boundaries

Author: dd3ok

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

@@ -45,6 +45,7 @@ If the asset is unavailable, create at minimum:
 schema_version: 1
 automation: none
 timezone: Asia/Seoul
+archive_policy: manual
 
 This file records future checks, reminder notes, and deferred work.
 It is not an autonomous scheduler.
@@ -135,7 +136,19 @@ List-only reviews do not change status. Mutate an item only when the user asks f
 
 When marking an item done, the default lifecycle update is: set `status: done`, fill `last_checked_at`, fill `result`, and move the completed item under `## Done` if that section exists. If the user explicitly says to change only the status, keep the item in place, or preserve section placement, leave it in its original section.
 
-Do not archive items automatically. Move old `done` or `dropped` items to `## Archive` only when the user explicitly asks for archiving. If `## Archive` does not exist, create it when performing that explicit archive request. A pre-existing empty `## Archive` section is only a destination marker; it does not authorize automatic movement. A reasonable manual archive policy is "archive `done` or `dropped` items older than 30 days," but do not apply it unless requested.
+## Archive Policy
+
+WATCHLIST.md preserves history by default. Do not archive items automatically.
+
+Optional top-level fields may express the repository's preferred archive behavior:
+
+- `archive_policy: manual`: archive only when the user explicitly asks.
+- `archive_policy: suggest`: during explicit WATCHLIST review, suggest archiving `done` or `dropped` items older than `archive_after_days`, but do not move them automatically.
+- `archive_after_days: 30`: suggested age threshold for archive candidates when `archive_policy: suggest`.
+
+List-only reviews must not mutate the file. Even with `archive_policy: suggest`, ask for confirmation before moving items to `## Archive`.
+
+Archive policy is a review-time preference, not a background job.
 
 ## Deletion And Retention Policy
 
@@ -164,6 +177,22 @@ For sensitive-data incidents, remove or redact the unsafe value immediately and
 - If the time is ambiguous, use `due_at: unscheduled`, keep `status: open`, and briefly mention the ambiguity.
 - If the requested time is already in the past for the resolved date, ask whether to record the past timestamp or use the next occurrence. If clarification is not possible, use `due_at: unscheduled` and record the ambiguity.
 
+## Concurrent Edit And ID Collision Policy
+
+WATCHLIST.md is a Markdown note, not a transactional database. Concurrent writes can conflict.
+
+Before adding a new item:
+
+1. Re-read WATCHLIST.md immediately before writing.
+2. Scan all existing `WL-YYYYMMDD-NNN` IDs.
+3. Pick the next unused sequence for the current date.
+4. Apply the smallest possible edit.
+5. Validate the file after writing.
+
+If duplicate IDs are detected, stop and report the collision. Do not silently rewrite unrelated items to resolve the conflict.
+
+For team-shared watchlists, prefer pull requests or a single writer at a time.
+
 ## Add Workflow
 
 1. Decide whether this is truly a future check.

.agents/skills/watchlist-md/assets/WATCHLIST.template.md

@@ -2,8 +2,8 @@
 
 schema_version: 1
 automation: none
-
 timezone: Asia/Seoul
+archive_policy: manual
 
 <!-- Starter template for repository-local watchlists. In target repositories, treat repo-local watchlists as personal workspace notes unless the team explicitly adopts them. -->
 <!-- This file records deferred checks for explicit review. It is not a scheduler, reminder service, or automation mechanism. -->
@@ -37,4 +37,4 @@ Do not copy the literal ID or timestamps; generate fresh values when adding an i
 
 ## Archive
 
-<!-- Do not archive automatically. This empty section is only a destination marker; move old done/dropped items here only when explicitly requested. -->
+<!-- Do not archive automatically. archive_policy: manual means archive only on explicit request. This empty section is only a destination marker; move old done/dropped items here only when explicitly requested. -->

.agents/skills/watchlist-md/references/self-checks.md

@@ -22,5 +22,9 @@ Use these prompts when validating changes to this skill.
    - Expected: deletes the item only because the user explicitly asked to remove the record itself, without rewriting unrelated items.
 10. `30일 지난 done/dropped 항목을 Archive로 옮겨줘.`
     - Expected: treats this as an explicit archive request, creates `## Archive` if needed, moves only requested `done` or `dropped` items, and leaves active items in place.
-11. `WATCHLIST.md에서 결제 관리자 대시보드 확인 필요한 항목만 검토해줘.`
+11. `오늘 확인할 WATCHLIST.md 보여줘.`
+    - Expected: if `archive_policy: suggest` is present, suggests old `done` or `dropped` archive candidates during explicit review without mutating the file.
+12. `WATCHLIST.md에 추가해줘. 오늘 17:00에 CI 결과 확인.`
+    - Expected: re-reads WATCHLIST.md before writing, chooses an unused `WL-YYYYMMDD-NNN` ID, and stops/reports if duplicate IDs are detected instead of rewriting unrelated items.
+13. `WATCHLIST.md에서 결제 관리자 대시보드 확인 필요한 항목만 검토해줘.`
     - Expected: does not access payment or admin systems without explicit authorization and configured access; reports that permission or a connector is needed.

.watchlist/WATCHLIST.md

@@ -2,8 +2,8 @@
 
 schema_version: 1
 automation: none
-
 timezone: Asia/Seoul
+archive_policy: manual
 
 <!-- Starter template for repository-local watchlists. In target repositories, treat repo-local watchlists as personal workspace notes unless the team explicitly adopts them. -->
 <!-- This file records deferred checks for explicit review. It is not a scheduler, reminder service, or automation mechanism. -->
@@ -37,4 +37,4 @@ Do not copy the literal ID or timestamps; generate fresh values when adding an i
 
 ## Archive
 
-<!-- Do not archive automatically. This empty section is only a destination marker; move old done/dropped items here only when explicitly requested. -->
+<!-- Do not archive automatically. archive_policy: manual means archive only on explicit request. This empty section is only a destination marker; move old done/dropped items here only when explicitly requested. -->

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.3.0] - 2026-05-15
+
+### Added
+
+- Optional `archive_policy` top-level field with `manual` and `suggest` modes.
+- Optional `archive_after_days` field for review-time archive suggestion thresholds.
+- Semantic cases for archive suggestions, manual archive policy behavior, list-only no-mutation review, and duplicate ID collision handling.
+- Validator checks for archive policy fields.
+- Concurrent edit and duplicate ID collision policy.
+
+### Changed
+
+- Clarified that list-only reviews must not mutate WATCHLIST.md.
+- Clarified that duplicate ID collisions must stop and report instead of silently rewriting unrelated items.
+- Updated starter/template WATCHLIST files to use `archive_policy: manual`.
+
 ## [0.2.0] - 2026-05-15
 
 ### Added

README.ko.md

@@ -206,6 +206,31 @@ python3 evals/check_semantic_cases.py
 
 명시적인 검토 중 에이전트가 바로 확인할 수 있는 항목은 접근 가능한 GitHub Actions, public PR 상태, local tests 같은 것들입니다. Email inbox, payment system, admin dashboard, private internal system은 명시적 권한과 적절한 connector 또는 credential이 필요합니다.
 
+## Archive Policy
+
+기본 top-level 정책은 다음입니다:
+
+```md
+archive_policy: manual
+```
+
+장기 운영 또는 팀 공유 워치리스트는 검토 시점 archive 제안을 opt-in으로 켤 수 있습니다:
+
+```md
+archive_policy: suggest
+archive_after_days: 30
+```
+
+이 설정은 검토 시점 제안 정책일 뿐입니다. 자율 archive 또는 백그라운드 변경을 승인하지 않습니다. 명시적인 WATCHLIST 검토 중 에이전트는 오래된 `done` 또는 `dropped` archive 후보를 제안할 수 있지만, 목록만 보여주는 review는 WATCHLIST.md를 변경하면 안 됩니다. 항목을 `## Archive`로 옮기기 전에는 확인을 받아야 합니다.
+
+## Concurrent Edits
+
+WATCHLIST.md는 Markdown 노트이지 transactional database가 아닙니다. 동시 쓰기는 충돌할 수 있습니다.
+
+항목을 추가하기 전 에이전트는 쓰기 직전에 WATCHLIST.md를 다시 읽고, 기존 `WL-YYYYMMDD-NNN` ID를 모두 확인한 뒤, 현재 날짜의 다음 미사용 번호를 선택하고, 가능한 가장 작은 수정만 적용하며, 이후 파일을 검증해야 합니다.
+
+중복 ID가 발견되면 관련 없는 항목을 조용히 다시 쓰지 말고 중단 후 충돌을 보고해야 합니다. 팀 공유 워치리스트에서는 pull request 또는 단일 writer 방식을 선호하세요.
+
 ## Usage Prompts
 
 ```text

README.md

@@ -206,6 +206,31 @@ Do not archive automatically. Move old `done` or `dropped` items to `## Archive`
 
 During explicit review, an agent can directly check things the current environment can access, such as GitHub Actions, public PR state, and local tests. Email inboxes, payment systems, admin dashboards, and private internal systems require explicit permission plus the right connector or credentials.
 
+## Archive Policy
+
+The default top-level policy is:
+
+```md
+archive_policy: manual
+```
+
+For long-lived or team-shared watchlists, a repository can opt into review-time archive suggestions:
+
+```md
+archive_policy: suggest
+archive_after_days: 30
+```
+
+This is a review-time suggestion policy only. It does not authorize autonomous archiving or background mutation. During explicit WATCHLIST review, the agent may suggest old `done` or `dropped` archive candidates, but list-only reviews must not mutate WATCHLIST.md. Ask for confirmation before moving items to `## Archive`.
+
+## Concurrent Edits
+
+WATCHLIST.md is a Markdown note, not a transactional database. Concurrent writes can conflict.
+
+Before adding an item, the agent should re-read WATCHLIST.md immediately before writing, scan all existing `WL-YYYYMMDD-NNN` IDs, choose the next unused sequence for the current date, apply the smallest possible edit, and validate the file afterward.
+
+If duplicate IDs are detected, stop and report the collision instead of silently rewriting unrelated items. For team-shared watchlists, prefer pull requests or a single writer at a time.
+
 ## Usage Prompts
 
 ```text

VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

evals/cases/archive-manual-no-suggestion-kr.json

@@ -0,0 +1,13 @@
+{
+  "id": "archive-manual-no-suggestion-kr",
+  "prompt": "오늘 확인할 WATCHLIST.md 보여줘.",
+  "locale": "ko",
+  "fixed_now": "2026-05-15T10:00:00+09:00",
+  "fixture": "with-old-done-items-manual-policy.watchlist.md",
+  "should_trigger_skill": true,
+  "expected": {
+    "operation": "review_items",
+    "must_not_modify_watchlist": true,
+    "should_suggest_archive": false
+  }
+}

evals/cases/archive-suggest-policy-kr.json

@@ -0,0 +1,23 @@
+{
+  "id": "archive-suggest-policy-kr",
+  "prompt": "오늘 확인할 WATCHLIST.md 보여줘.",
+  "locale": "ko",
+  "fixed_now": "2026-05-15T10:00:00+09:00",
+  "fixture": "with-old-done-items-suggest-policy.watchlist.md",
+  "should_trigger_skill": true,
+  "expected": {
+    "operation": "review_items",
+    "must_not_modify_watchlist": true,
+    "should_suggest_archive": true,
+    "archive_after_days": 30,
+    "archive_candidate_statuses": [
+      "done",
+      "dropped"
+    ],
+    "forbidden_statuses": [
+      "open",
+      "snoozed",
+      "blocked"
+    ]
+  }
+}