@nolit/dsh-notify 0.0.0-stage → 0.0.1-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/CHANGELOG.md +388 -0
  2. package/LICENSE +21 -0
  3. package/PROVENANCE.md +96 -0
  4. package/README.md +298 -2
  5. package/cordis.patch.yml +19 -0
  6. package/docs/2026-10-20-dsh-notify-design.md +335 -0
  7. package/docs/2026-10-20-final-status.md +125 -0
  8. package/docs/2026-10-23-asset-policy.md +170 -0
  9. package/docs/2026-10-23-deployment-strategy-review.md +530 -0
  10. package/docs/2026-10-23-headless-nonintrusive-ui-architecture.md +579 -0
  11. package/docs/2026-10-23-hybrid-dual-mode-design.md +955 -0
  12. package/docs/2026-10-23-timezone-global-report.md +204 -0
  13. package/docs/2026-10-23-web-notify-plugin-spec.md +454 -0
  14. package/docs/2026-10-23-web-plugin-mount.md +111 -0
  15. package/docs/2026-10-23-windows-widget-poc-report.md +312 -0
  16. package/docs/2026-10-24-linux-desktop-verification.md +134 -0
  17. package/docs/BOOT-CARD.md +176 -0
  18. package/docs/RECOVERY-NOTES.md +111 -0
  19. package/docs/WORK-PROTOCOL.md +155 -0
  20. package/docs/deepseek-peak-spec.md +370 -0
  21. package/docs/dsh-harness-notify-spec.md +149 -0
  22. package/icon.svg +6 -0
  23. package/lib/client.js +2172 -0
  24. package/lib/client.src.js +1963 -0
  25. package/lib/index.js +13 -0
  26. package/lib/locale-table.js +215 -0
  27. package/locale/en.json +104 -0
  28. package/locale/ko.json +104 -0
  29. package/market/icons/dsh-notify.svg +6 -0
  30. package/market/index.json +77 -0
  31. package/package.json +80 -4
  32. package/scripts/build-client.mjs +41 -0
  33. package/scripts/gen-locale.mjs +36 -0
  34. package/test/client.test.mjs +601 -0
  35. package/test/locale.test.mjs +114 -0
  36. package/test/manifest.test.mjs +115 -0
  37. package/test/peak.test.mjs +333 -0
  38. package/test/typography.test.mjs +85 -0
@@ -0,0 +1,176 @@
1
+ # BOOT CARD — 새 작업창 진입 카드
2
+
3
+ <!-- skeleton:
4
+ version: 1.0
5
+ kind: boot
6
+ status: historical
7
+ updated: 2026-10-24
8
+ summary: The track-local boot card used when dsh-notify was its own workspace; superseded by workspace bootcards/.
9
+ -->
10
+
11
+
12
+ > 상태: final · 최종 갱신: 2026-10-20 · git: main @ milestone-3 · 상위: [WORK-PROTOCOL.md](WORK-PROTOCOL.md)
13
+
14
+ > 이 카드는 **새 작업창에서 가장 먼저 읽는 문서**다. 여기까지 읽었으면 바로 작업을 시작할 수 있다.
15
+
16
+ ## 인덱스
17
+
18
+ | § | 섹션 | 이동 | 한 줄 요약 |
19
+ |---|---|---|---|
20
+ | 1 | 한 줄 정의 | [§1](#한-줄-정의) | 트레이·반투명 창 알림 플랫폼 |
21
+ | 2 | 작업 디렉터리 | [§2](#작업-디렉터리) | 이 프로젝트 경로 |
22
+ | 3 | 읽는 순서 | [§3](#읽는-순서) | 설계 → 스펙 → 카드 |
23
+ | 4 | 현재 상태 | [§4](#현재-상태) | 문서 완료, 판정 코어 구현 |
24
+ | 5 | 확정된 사실 | [§5](#확정된-사실-재조사-불필요) | 요금·공휴일·환경 실측 |
25
+ | 6 | 미결 사항 | [§6](#미결-사항--구현-중-결정) | 구현 중 결정할 것 |
26
+ | 7 | 첫 작업 지시 | [§7](#첫-작업-지시) | 테스트 먼저 |
27
+ | 8 | 구현 시 주의 | [§8](#구현-시-주의) | UTC 날짜·안전 강등 |
28
+ | 9 | 작업 규약 | [§9](#작업-규약--git-flag--헤더인덱스) | GIT FLAG 3지점, 헤더/인덱스 선행 |
29
+ | 10 | 다른 작업창과의 관계 | [§10](#참고--다른-작업창과의-관계) | 독립 프로젝트 |
30
+
31
+ ---
32
+
33
+ ## 한 줄 정의
34
+
35
+ `DSH Notify`는 DeepSeek Harness 작업 중 필요한 외부 상태를 Windows 트레이와 반투명 창으로 상시 보여주는 로컬 알림 플랫폼이다. 첫 기능은 **DeepSeek 과금 구간(피크 100% / 오프피크 50%) 인디케이터**다.
36
+
37
+ ---
38
+
39
+ ## 작업 디렉터리
40
+
41
+ ```
42
+ C:\Users\nolit\Workspace\projects\DSH Notify
43
+ ```
44
+
45
+ 새 작업창의 작업 디렉터리를 위 경로로 지정한다.
46
+
47
+ ---
48
+
49
+ ## 읽는 순서
50
+
51
+ | 순서 | 문서 | 목적 |
52
+ |---|---|---|
53
+ | 1 | `docs\2026-10-20-dsh-notify-design.md` | 플랫폼 구조, provider 계약, UI·설정·오류 처리 |
54
+ | 2 | `docs\deepseek-peak-spec.md` | 첫 기능의 요금 규칙, 판정 함수, 테스트 표 |
55
+ | 3 | 이 카드 | 진입점 |
56
+
57
+ 설계 문서를 읽지 않고 구현하면 provider 계약을 어기게 된다. 반드시 1 → 2 순서로 읽는다.
58
+
59
+ ---
60
+
61
+ ## 현재 상태
62
+
63
+ | 항목 | 상태 |
64
+ |---|---|
65
+ | 설계 문서 | 완료 |
66
+ | 기능 스펙 | 완료 |
67
+ | 폴더 구조 | 생성됨 (`providers`, `ui`, `notify`, `tests`, `docs`) |
68
+ | 작업 규약 | 완료 ([WORK-PROTOCOL.md](WORK-PROTOCOL.md)) |
69
+ | git | `main @ milestone-3` (태그 목록: `git tag --list 'milestone-*'`) |
70
+ | 판정 코어 | 완료 — `providers\deepseek-peak.ps1` |
71
+ | UI·상주 프로세스 | 완료 — `core.ps1`, `ui\presenter.ps1`, `ui\indicator.ps1`, `ui\tray.ps1` |
72
+ | 실행 | `install-shortcut.ps1` (시작 메뉴) 또는 `start.ps1` (자동 시작 등록은 안 함) |
73
+ | 단일 exe | `build\build-exe.ps1` — 이 PC는 Smart App Control 로 실행 차단 |
74
+ | DSH 완료 팝업 | 완료 — 브리지 → `cache\popup-request.json` → 코어 팝업 (소리 없음) |
75
+ | 마감 문서 | [2026-10-20-final-status.md](2026-10-20-final-status.md) — 알려진 문제 포함 |
76
+ | 미구현 | 자동 시작 토글, 추가 provider(세션/예약), 알림음 |
77
+
78
+ **상주 앱이 동작한다.** 새 작업은 `tests\run-all.ps1` 이 초록인 상태에서 시작하고,
79
+ UI 변경 시 `pwsh -Sta -File ui\render-indicator.ps1 -Severity alert -Out out.png` 로 먼저 눈으로 확인한다.
80
+
81
+ ---
82
+
83
+ ## 확정된 사실 (재조사 불필요)
84
+
85
+ ### 요금 규칙
86
+
87
+ - 피크: UTC 01–04, 06–10, **월–금**
88
+ - 한국 시간: **평일 10–13, 15–19**
89
+ - 오프피크 = 피크의 0.5배
90
+ - 출처: [Models & Pricing](https://api-docs.deepseek.com/quick_start/pricing) 직접 확인
91
+
92
+ ### 공휴일 데이터
93
+
94
+ - 소스: [NateScarlet/holiday-cn](https://github.com/NateScarlet/holiday-cn)
95
+ - URL: `https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/{year}.json`
96
+ - **2026.json 검증 완료** — `papers[]`가 국무원 원문(`content_7047091.htm`)을 가리키며, 직접 받은 공고와 완전 일치
97
+ - `isOffDay: false` = 대체근무일
98
+ - **2027.json 은 지금 비어 있음** — 국무원 공고(매년 11월) 전
99
+
100
+ ### 기술 환경 (확인 완료)
101
+
102
+ - PowerShell **7.6.7**
103
+ - `System.Windows.Forms` 로드 성공
104
+ - `PresentationFramework` (WPF) 로드 성공
105
+ - `schtasks.exe` 존재
106
+
107
+ ### 실측값
108
+
109
+ - 2026-10-20 01:12 KST → **오프피크** (UTC 2026-10-19 16시)
110
+
111
+ ---
112
+
113
+ ## 미결 사항 — 구현 중 결정
114
+
115
+ | 항목 | 선택지 | 메모 |
116
+ |---|---|---|
117
+ | 자동 시작 | `HKCU\...\Run` 등록할지 | 사용자에게 물어본다 |
118
+ | 대체근무일 | 피크로 볼지 | 설정 플래그 `treatMakeupAsPeak`, 기본 `true` |
119
+ | 공휴일 갱신 주기 | 10일 유지 → 운영 후 재판단 | `refreshHours: 240` (2026-10-20 결정). 재검토 지표: 갱신 실패 빈도, 연중 추가 공고 발생, 놓친 임시휴일로 인한 실제 혼선 |
120
+ | 공인 IP 지역 검사 | 한다 — 하루 1회, 표시용 | 노트북은 KST 로 고정된 채 해외에 있을 수 있어 기기 시간대만으로는 현지 시각을 모른다. 판정은 UTC 고정이라 영향 없음. `Get-PeakReferenceTimeZones` 가 두 시간대·불일치를 반환 (spec §4.4) |
121
+ | 향후 provider | 세션/작업/예약 중 우선순위 | 첫 기능 검증 후 |
122
+ | `C:\Users\nolit\deepseek-peak-dsh` | 삭제할지 보류할지 | DSH 플러그인 초안. 이 계획에서 미사용 |
123
+
124
+ ---
125
+
126
+ ## 첫 작업 지시
127
+
128
+ 1. `docs\deepseek-peak-spec.md` §5 의 테스트 표를 연다
129
+ 2. `tests\peak-decisions.ps1` 부터 작성한다 — **테스트 먼저**
130
+ 3. `providers\deepseek-peak.ps1` 의 `Get-PeakDecision` 을 구현해 8개 케이스를 통과시킨다
131
+ 4. 통과 후 공휴일 캐시 로더를 붙인다
132
+ 5. 그다음 UI (`ui\indicator.ps1`, `ui\tray.ps1`)
133
+
134
+ **1~5 완료.** 판정·캐시·시간대·토스트·아이콘·카드·트레이·상주 루프까지 초록이다.
135
+ 다음 후보: 자동 시작 토글, 추가 provider(세션 길이·예약), 클릭 시 GUI 열기(COM activator).
136
+
137
+ **테스트 없이 UI 부터 만들지 않는다.** 판정이 틀리면 UI가 아무리 예뻐도 쓸모없다.
138
+
139
+ ---
140
+
141
+ ## 구현 시 주의
142
+
143
+ - **공휴일 판정은 UTC 날짜 기준.** KST 날짜로 바꾸면 자정 부근에서 하루 어긋난다
144
+ - **정보 부족 시 안전 강등**: 캐시 → 주말 규칙 → 추정 표시. 조용히 틀리지 않는다
145
+ - **provider 실패는 격리**: 하나 죽어도 나머지는 계속
146
+ - **알림은 전환 시 1회만**: 같은 구간 내 반복 금지
147
+
148
+ ---
149
+
150
+ ## 작업 규약 — GIT FLAG · 헤더/인덱스
151
+
152
+ 전문은 [WORK-PROTOCOL.md](WORK-PROTOCOL.md). 여기에는 요약만 둔다. 새 작업창은 이 두 규칙을 **작업 전에** 세운다.
153
+
154
+ ### GIT FLAG — 세 지점
155
+
156
+ | 지점 | 할 일 |
157
+ |---|---|
158
+ | START | `git status --short --branch` 로 트리 확인 → `git log -1 --format='%h %s'` 기준 해시 확인. 더러우면 먼저 기준 커밋 |
159
+ | STEP | 한 단계의 테스트가 **초록이 된 직후** 커밋. 실패 상태 커밋 금지 |
160
+ | END | `git status` clean 확인 → HEAD 해시 사용자에게 보고 |
161
+
162
+ 커밋 형식: `<type>(<scope>): <요약>` + 본문 `왜 / 검증 / 결과`. 마일스톤에는 `milestone-N` 태그.
163
+
164
+ ### 헤더 + 스켈레톤 인덱스 선행
165
+
166
+ - **문서**: 제목 아래 `> 상태: active · 최종 갱신: 날짜 · git: main @ milestone-N · 상위: 링크` 한 줄, 이어서 `## 인덱스` 표
167
+ - **스크립트**: `<# .SYNOPSIS ... #>` 헤더 + `#region INDEX` (줄번호 대신 심볼명 · 목적 · 대응 테스트)
168
+ - 파일을 쓰기 전에 헤더와 뼈대 인덱스를 먼저 만들고 내용을 채운다
169
+ - 구조(섹션·심볼)를 바꾸면 **같은 커밋에서** 인덱스를 갱신한다
170
+ - 강제 수단: `tests\docs-contract.ps1`, 전체 실행 `tests\run-all.ps1`
171
+
172
+ ---
173
+
174
+ ## 참고 — 다른 작업창과의 관계
175
+
176
+ 이 프로젝트는 원래 일반 작업창에서 계획했다. 그 창은 **DSH 설치·정리 작업용**으로 계속 쓴다. 이 프로젝트는 독립적이며 DSH 프로필을 건드리지 않는다.
@@ -0,0 +1,111 @@
1
+ # RECOVERY NOTES — what was restored, how, and what is still missing
2
+
3
+ <!-- skeleton:
4
+ version: 1.0
5
+ kind: reference
6
+ status: reference
7
+ updated: 2026-10-24
8
+ summary: What was restored into this track, how it was restored, and which pieces are still missing.
9
+ -->
10
+
11
+
12
+ > Track: `dsh-plugins/dsh-notify` · recovery date: 2026-10-24 · sources: 8 DSH session logs (see `../PROVENANCE.md`)
13
+
14
+ This document is the honest gap report for the reconstruction. Nothing below was invented: every
15
+ restored file comes from a `write`/`edit` tool call, a full-file `read` tool result, or an
16
+ explicit shell mutation captured in the session logs.
17
+
18
+ ## 1. Files missing from the replayed staging tree, now recovered
19
+
20
+ The staging replay (`/tmp/reconstruct/notify`) only replayed `write`/`edit` tool calls, so files
21
+ created before logging started (or mutated only through PowerShell here-strings) were absent or
22
+ stale. The following were recovered and **verified against every later `read` snapshot** (0 line
23
+ mismatches at each check):
24
+
25
+ | File | Status | Evidence used |
26
+ |---|---|---|
27
+ | `docs/BOOT-CARD.md` | **recovered, 167 lines** | full `read` at session a3b2bf75 seq 39 (113 lines) → replayed through 12 later `edit` calls + 1 PowerShell `Replace` (milestone-3/final status block); all 5 later read snapshots match |
28
+ | `docs/2026-10-20-dsh-notify-design.md` | **recovered, 326 lines** | full `read` at a3b2bf75 seq 51 (260 lines) → replayed through 25 later `edit` calls + 2 PowerShell `Replace` calls; all 16 later read snapshots match |
29
+ | `docs/deepseek-peak-spec.md` | **recovered, 361 lines** | full `read` at a3b2bf75 seq 57 (258 lines) → replayed through 15 later `edit` calls; all 12 later read snapshots match |
30
+ | `README.md` (now `prototype-windows/README.md`) | **recovered, 156 lines** | full `read` at b53400d8 seq 46 (115 lines, already post-dates earlier shell mutations) → replayed through 14 later `edit` calls; all 4 later read snapshots match |
31
+ | `.gitignore` (now `prototype-windows/.gitignore`) | **recovered, 18 lines** | full `read` at b53400d8 seq 2621; one later logged `edit` applied |
32
+ | `plugin/market/icons/dsh-notify.svg` (now `market/icons/dsh-notify.svg`) | **recovered** | log shows it was created by `Copy-Item plugin/icon.svg → plugin/market/icons/dsh-notify.svg` (b53400d8 seq 959); recreated as that byte-identical copy of `icon.svg` |
33
+ | `plugin/LICENSE` (now root `LICENSE`) | **recovered verbatim** | written by `write` (MIT, "Copyright (c) 2026 nolit"); the in-log `Copy-Item LICENSE → plugin/LICENSE` is the same text |
34
+ | `ui/assets/digital-7-license.txt` | **recovered, full text** | full `read` result in a3b2bf75; the `.ttf` binary itself is unrecoverable (see §3) |
35
+ | `docs/2026-10-20-final-status.md`, `docs/dsh-harness-notify-spec.md`, `prototype-windows/bridge/index.js`, `prototype-windows/notify/popup.ps1`, `prototype-windows/tests/docs-contract.ps1` | **refreshed to last verified state** | staging was stale for these five; replaced with the latest full `read` snapshot taken after their last mutation (b53400d8, 2026-10-22 18:28–19:37) |
36
+
37
+ ## 2. PowerShell in-place mutations that a write/edit replay cannot see
38
+
39
+ The staging replay captured the `write`/`edit` tools but not shell commands such as
40
+ `[IO.File]::WriteAllText(...)` / `$text.Replace(...)` / `Set-Content`. Mutations that were
41
+ verifiable and not superseded by a later `write`/`edit` were re-applied by hand:
42
+
43
+ - `prototype-windows/tests/core-config.ps1` — default opacity expectation 0.82 → 0.6 and
44
+ `'현지 18:00–21:00 (UTC-7)'` → `'Local 18:00–21:00 (UTC-7)'` (a3b2bf75 seq 2456/2896/2922;
45
+ confirmed by the b53400d8 read at 19:33).
46
+ - `prototype-windows/tests/presenter.ps1` — opacity 0.82 → 0.6, title expectations
47
+ `'DeepSeek 피크 (100%)'` → `'DeepSeek Peak (100%)'` / `'DeepSeek 오프피크 (50%)'` → `'DeepSeek Off-Peak (50%)'`.
48
+ - `prototype-windows/tests/indicator-render.ps1` — brightness threshold 140 → 100
49
+ (a3b2bf75 seq 3073, after the file's last write).
50
+ - `prototype-windows/ui/render-indicator.ps1` — local label `현지 18:00–21:00 (PDT)` →
51
+ `Local 18:00–21:00 (UTC-7)`.
52
+ - `prototype-windows/start.cmd` — rewritable shell entry point was replaced by a here-string
53
+ command (b53400d8 seq 2731: adds `chcp 65001`, UIPI re-launch guard, `app\core.ps1` fallback);
54
+ restored with the logged content and CRLF line endings.
55
+
56
+ Files whose staging content was already produced by a later `write`/`edit` were deliberately
57
+ **not** patched (e.g. `config.ps1`, `ui/presenter.ps1`, `ui/indicator.ps1`), to avoid
58
+ overwriting authoritative tool-call content with an older shell edit.
59
+
60
+ **Residual risk:** for a handful of prototype files the last logged event is a shell mutation
61
+ whose exact resulting text is not fully verifiable from a later read (e.g. hand-edited EOL/BOM
62
+ changes). Those files keep the staging content; they may differ from the Windows machine's final
63
+ bytes by whitespace/encoding only. They are never executed by this track.
64
+
65
+ ## 3. Not recoverable (no content in any session log)
66
+
67
+ These runtime/generated assets are referenced by the recovered prototype but their bytes are not
68
+ in the logs. **No placeholder files were fabricated:**
69
+
70
+ - `ui/assets/digital-7.ttf` (user-supplied font, licence text was recovered)
71
+ - `ui/assets/deepseek-logo.png` (user-supplied DeepSeek wordmark)
72
+ - `ui/icons/*.ico` and `ui/icons/preview.png` (generated by `ui/build-icons.ps1` / `ui/icons.ps1`)
73
+ - `ui/previews/indicator-alert.png`, `ui/previews/indicator-ok.png` (rendered screenshots)
74
+ - `notify/ding.wav`, `cache/ding-custom.wav` (generated audio; later removed under the BYO asset policy)
75
+ - `cache/deepseek-peak/2026.json` (holiday data fetched from GitHub at runtime),
76
+ `cache/region.json`, `cache/*.log`, `config.json`, `runtime.json`, `events.jsonl`
77
+ - `DSH-Notify.exe` and `dist/DSH-Notify-Portable*` build outputs
78
+ - `docs/previews/*.png` images referenced by the design doc
79
+ - `THIRD-PARTY-NOTICES.md` — no such file appears in any of the eight session logs (the project
80
+ tracked third-party notices in `docs/2026-10-23-asset-policy.md` instead), so none was created.
81
+
82
+ `prototype-windows/cache/.gitkeep` is the one intentional **empty file** in this track: it is the
83
+ recovered git keep-marker for the runtime cache directory (it was 0 bytes in the original repo).
84
+
85
+ ## 4. Structural notes / deliberate deviations
86
+
87
+ - The original project was one tree (`README.md`, `docs/`, `core.ps1`, `plugin/`, …). This track
88
+ promotes the **plugin package** to the root (as requested for the unified workspace) and moves
89
+ everything else under `prototype-windows/`. The project `docs/` folder is promoted to
90
+ `../docs/` (track root) rather than `prototype-windows/docs/`.
91
+ - Because of that move, some recovered relative links no longer resolve inside this track
92
+ (e.g. plugin `README.md`'s `../docs/…` link, prototype `README.md`'s `docs/…` links). The text
93
+ is preserved verbatim; links were **not** rewritten.
94
+ - `package.json` was recovered verbatim except for one manifest-metadata change:
95
+ `"test/client.test.mjs"` was added to the `files` array so the committed test file is covered
96
+ by the package manifest. No runtime behavior, exports, or DSH metadata changed.
97
+ - `market/icons/dsh-notify.svg` is a copy of `icon.svg`, matching the original `Copy-Item`.
98
+ - `prototype-windows/LICENSE` duplicates the root MIT licence because the original project root
99
+ carried the same licence file.
100
+
101
+ ## 5. Validation performed on this track (2026-10-24, Linux, Node.js v24.2.0)
102
+
103
+ - JSON: all 5 JSON files parse (`node -e JSON.parse(...)`) — **PASS**.
104
+ - ESM: all 6 `.js`/`.mjs` files parse as ESM (`node --input-type=module --check < file`) — **PASS**.
105
+ - Tests: `node --test test/client.test.mjs` — **15 passed / 0 failed** (browser APIs are mocked; no
106
+ DOM/jsdom needed). The plugin also self-reports `exports.__test` for headless core checks.
107
+ - Manifest: `dsh.manifestVersion = 1`, `dsh.client.platform = "web"`, `exports["./client"] = "./lib/client.js"`,
108
+ `files` covers every package file — **PASS**.
109
+ - PowerShell/JScript was **not** executed: `pwsh`/WPF/`wscript` are Windows-only and unavailable on
110
+ this Linux host. The prototype is preserved as source, not validated by execution.
111
+ - No network access, no package installation, no writes outside this track and `/tmp`.
@@ -0,0 +1,155 @@
1
+ # 작업 규약 — GIT FLAG · 헤더/스켈레톤 인덱스
2
+
3
+ <!-- skeleton:
4
+ version: 1.0
5
+ kind: policy
6
+ status: historical
7
+ updated: 2026-10-23
8
+ summary: Track-local work protocol covering git flags and the header/skeleton index convention; now owned by workspace docs/RULES.md.
9
+ -->
10
+
11
+
12
+ > 상태: active · 최종 갱신: 2026-10-20 · git: main @ milestone-1 · 상위: [BOOT-CARD.md](BOOT-CARD.md)
13
+
14
+ 이 문서는 새 작업창이 가장 먼저 따르는 규칙이다. 규칙은 문장으로만 두지 않는다 — `tests\docs-contract.ps1` 이 검사하고, 위반하면 테스트가 빨간불이 된다.
15
+
16
+ ---
17
+
18
+ ## 인덱스
19
+
20
+ | § | 섹션 | 이동 | 한 줄 요약 |
21
+ |---|---|---|---|
22
+ | 1 | GIT FLAG — 체크포인트 규약 | [§1](#1-git-flag--체크포인트-규약) | 시작·단계·종료 3지점에서 커밋으로 못 박는다 |
23
+ | 2 | 헤더 + 스켈레톤 인덱스 | [§2](#2-헤더--스켈레톤-인덱스) | 내용보다 뼈대·색인을 먼저 만든다 |
24
+ | 3 | 자동 검사 | [§3](#3-자동-검사) | docs-contract.ps1 이 위반을 차단한다 |
25
+ | 4 | 새 파일 체크리스트 | [§4](#4-새-파일-체크리스트) | 파일을 만질 때의 5단계 |
26
+
27
+ ---
28
+
29
+ ## 1. GIT FLAG — 체크포인트 규약
30
+
31
+ **원칙: 모든 작업은 커밋된 기준점 위에서 시작하고, 검증을 통과한 지점마다 커밋으로 못 박는다.**
32
+
33
+ ### 1.1 세 지점
34
+
35
+ | 지점 | 시점 | 명령 | 통과 조건 |
36
+ |---|---|---|---|
37
+ | **START** | 작업 시작 직전 | `git status --short --branch` → `git log -1 --format='%h %s'` | 트리가 깨끗하고 기준 커밋 해시를 확인했다 |
38
+ | **STEP** | 한 단계의 검증(테스트 실행) 통과 직후 | `git add <이 단계 파일>` → `git commit` | 그 단계 테스트가 실제로 초록이었다. 실패 상태 커밋 금지 |
39
+ | **END** | 작업 종료 시 | `git status` → `git log --oneline -n <세션 커밋 수>` | 트리가 깨끗하고, HEAD 해시를 사용자에게 보고했다 |
40
+
41
+ START 에서 트리가 더러우면 **새 작업을 시작하지 않고** 먼저 기준 커밋을 만든다. END 에서 더러운 파일이 남아 있으면 작업은 미완료다.
42
+
43
+ ### 1.2 커밋 메시지
44
+
45
+ ```
46
+ <type>(<scope>): <한 줄 요약>
47
+
48
+ 왜: <이 변경이 필요한 이유>
49
+ 검증: <실행한 명령>
50
+ 결과: <통과/실패 수치>
51
+ ```
52
+
53
+ - `type` ∈ `docs` `test` `feat` `fix` `chore`
54
+ - `scope` ∈ `protocol` `tests` `peak` `holiday` `provider` `repo`
55
+ - 한 커밋에 관련 없는 파일을 섞지 않는다. 히스토리를 재작성하지 않는다.
56
+
57
+ ### 1.3 마일스톤 태그
58
+
59
+ 마일스톤 커밋에는 주석 태그를 붙인다.
60
+
61
+ ```powershell
62
+ git tag -a milestone-2 -m "판정 코어 초록불"
63
+ git tag --list 'milestone-*'
64
+ ```
65
+
66
+ 헤더의 `git:` 필드는 완료된 마일스톤 **태그명**을 적는다. 커밋 해시를 제 자기 자신의 내용에 적는 것은 불가능하므로(자기 참조) 해시 대신 태그를 쓴다. 현재 HEAD 해시는 `git log -1 --format=%H` 로 언제든 확인한다.
67
+
68
+ ### 1.4 금지
69
+
70
+ - 실패하는 테스트를 포함한 커밋
71
+ - `git add -A` 로 무관한 파일 묶기
72
+ - 커밋 없이 여러 단계를 진행한 뒤 한 번에 커밋
73
+ - 강제 푸시·히스토리 재작성
74
+
75
+ ---
76
+
77
+ ## 2. 헤더 + 스켈레톤 인덱스
78
+
79
+ > **순서 규칙 — 파일을 쓰기 전에 헤더와 인덱스(뼈대)를 먼저 만든다. 그 다음에 내용을 채운다.**
80
+
81
+ 이유: 헤더가 목적·계약·검증 방법을 먼저 고정하면 본문이 그 목적에서 벗어나지 않고, 인덱스가 있으면 읽는 사람이 본문을 전부 읽지 않아도 구조를 파악할 수 있다.
82
+
83
+ ### 2.1 문서(`.md`) 헤더
84
+
85
+ 제목 바로 아래에 blockquote 1줄:
86
+
87
+ ```markdown
88
+ > 상태: active · 최종 갱신: YYYY-MM-DD · git: main @ milestone-N · 상위: <상대 링크>
89
+ ```
90
+
91
+ - `상태` ∈ `draft` `active` `frozen`
92
+ - 상위 문서가 없으면 `상위: -`
93
+
94
+ 이어서 `## 인덱스` 표:
95
+
96
+ ```markdown
97
+ ## 인덱스
98
+
99
+ | § | 섹션 | 이동 | 한 줄 요약 |
100
+ |---|---|---|---|
101
+ | 1 | 요금 규칙 | [§1](#1-요금-규칙) | 피크 창과 오프피크 비율 |
102
+ ```
103
+
104
+ - **섹션을 추가·삭제·순서 변경하면 같은 커밋에서 인덱스를 갱신한다.**
105
+ - 표는 본문과 같은 순서로 둔다.
106
+
107
+ ### 2.2 개발 파일(`.ps1`) 헤더
108
+
109
+ comment-based help 로 통일한다.
110
+
111
+ ```powershell
112
+ <#
113
+ .SYNOPSIS 한 줄 목적
114
+ .DESCRIPTION 동작 요약
115
+ .CONTRACT 준수하는 계약 위치 (예: docs\2026-10-20-dsh-notify-design.md §2.2)
116
+ .INPUTS 파라미터 의미
117
+ .OUTPUTS 반환 객체 형태
118
+ .SIDE-EFFECTS 네트워크/캐시 쓰기 여부
119
+ .TESTS 대응 테스트 파일과 케이스 번호
120
+ .NOTES 스펙 문서 절 참조
121
+ #>
122
+
123
+ #region INDEX
124
+ # Symbol 목적 대응 테스트
125
+ # Get-PeakDecision 과금 구간 판정 tests\peak-decisions.ps1 #1-9
126
+ #endregion
127
+ ```
128
+
129
+ - 코드 인덱스에는 **숫자 줄번호를 쓰지 않는다** — 코드가 움직이면 숫자가 거짓말을 한다. 심볼명·목적·테스트 케이스로 색인한다.
130
+ - 새 심볼을 추가하면 `#region INDEX` 도 같은 커밋에서 갱신한다.
131
+ - `Set-StrictMode` / `$ErrorActionPreference` 는 테스트 스크립트에만 적용한다(provider 는 상위 로더가 실패를 격리해야 하므로 스스로 던지지 않는다).
132
+
133
+ ---
134
+
135
+ ## 3. 자동 검사
136
+
137
+ `tests\docs-contract.ps1` 이 저장소 전체를 훑어 아래를 검사한다.
138
+
139
+ | 대상 | 검사 |
140
+ |---|---|
141
+ | `README.md`, `docs\*.md` | 제목 다음 8줄 안에 `> 상태:` 헤더 줄, 그리고 `## 인덱스` 절 |
142
+ | `providers\*.ps1`, `tests\*.ps1` | `<#` 블록 안 `.SYNOPSIS`, 그리고 `#region INDEX` |
143
+ | 그 외 | 검사 대상 아님 (`.gitkeep`, `cache\`, `config.json`) |
144
+
145
+ 위반이 있으면 파일과 사유를 출력하고 종료코드 1. 전체 테스트는 `tests\run-all.ps1` 로 돌린다.
146
+
147
+ ---
148
+
149
+ ## 4. 새 파일 체크리스트
150
+
151
+ 1. 이 문서의 템플릿으로 **헤더**를 쓴다
152
+ 2. 섹션/심볼 목록으로 **인덱스(빈 뼈대)** 를 쓴다
153
+ 3. 본문 또는 구현을 채운다
154
+ 4. 인덱스와 실제 구조가 일치하는지 확인한다
155
+ 5. `tests\run-all.ps1` 초록 확인 후 STEP 커밋