tink-harness 1.2.1 → 1.2.2

package/docs/repo-signals.md

@@ -1,77 +1,95 @@
-# Repo Signals
-
-Repo signals are small, static hints that help `/tink:cast` choose context and verification without adding a new command surface.
-
-They are not a generated index, not a cache, and not a `tink index` command. In this phase, repo signals live in fixtures so the behavior can be reviewed and tested before any runtime automation exists.
-
-Repo signals follow the project compatibility baseline in `docs/compatibility-policy.md`: Claude Code and Codex must both be considered, and macOS and Windows must both remain supported.
-
-## Purpose
-
-Repo signals answer three questions:
-
-1. Which files usually move together?
-2. Which checks prove those files stayed consistent?
-3. Which changed paths are unknown to the current signal set?
-
-This lets Tink explain why a file was included in `context-map.json`, why a verification check was selected in `contract.json`, and when no check should be invented.
-
-## Current Fixtures
-
-- `tests/fixtures/repo-signals/tink-harness.json`: stable repo facts such as sync groups, instruction files, schema files, command surface, and verification hints.
-- `tests/fixtures/repo-signals/path-cases.json`: examples of changed paths and the verification hints they should select.
-- `tests/fixtures/current-run/context-map.json`: an example of context signals that cite repo signal sources.
-- `tests/fixtures/current-run/contract.json`: an example of selected verification hints written as manual checks.
-
-## Flow
-
-The intended cast flow is:
-
-```text
-changed path
--> matching repo signal verification_hints
--> contract.verification.manual_checks[]
--> context-map.json signals
-```
-
-For example:
-
-```text
-commands/cast.md
--> verification_hints.command-template-sync
--> manual check: test_dual_format_paths_stay_in_sync
--> context-map signal: verification_hint
-```
-
-The contract records what must be checked. The context map records why that check was selected.
-
-## Unmatched Paths
-
-If a changed path matches no verification hint, Tink should not invent a check.
-
-Instead, it records an `unmatched_path` signal in `context-map.json`.
-
-Example:
-
-```text
-docs/memory.md
--> no matching verification hint
--> no manual check added
--> context-map signal: unmatched_path
-```
-
-This keeps Tink honest. Unknown context is still visible, but it does not create fake certainty.
-
-## Boundaries
-
-Repo signal fixtures are advisory inputs.
-
-They must not:
-
-- run commands;
-- install tools;
-- write files;
-- create command surfaces;
-- behave like a runtime indexer.
-
-If runtime support is added later, it should preserve the same contract: signals explain context and verification choices, while checks still run through the normal verification flow.
+# Repo Signals
+
+Repo signals are small, static hints that help `/tink:cast` choose context and verification without adding a new command surface.
+
+They are not a generated index, not a cache, and not a `tink index` command. In this phase, repo signals live in fixtures so the behavior can be reviewed and tested before any runtime automation exists.
+
+Repo signals follow the project compatibility baseline in `docs/compatibility-policy.md`: Claude Code and Codex must both be considered, and macOS and Windows must both remain supported.
+
+## Purpose
+
+Repo signals answer four questions:
+
+1. Which files usually move together?
+2. Which checks prove those files stayed consistent?
+3. Which changed paths are unknown to the current signal set?
+4. Which small set of related context should cast inspect first?
+
+This lets Tink explain why a file was included in `context-map.json`, why a verification check was selected in `contract.json`, and when no check should be invented.
+
+## Context Graph Lite
+
+Phase 6 adds `context_graph_lite` to the static fixture. It is a small set of changed-path rules for cast. It is internal to `/tink:cast` and `$tink:cast`; it is not a new command, not a file watcher, and not a runtime indexer.
+
+Each rule has:
+
+- `when_paths`: changed path patterns that activate the rule.
+- `include_paths`: related files cast should consider first.
+- `signal_refs`: sync groups, verification commands, or verification hints that explain the selection.
+- `reason` and `confidence`: human-readable traceability for `context-map.json signals`.
+
+Context Graph Lite should prefer a small high-confidence context pack over a broad list. If no graph rule matches, Tink should record `unmatched_path` instead of inventing a relationship.
+
+## Current Fixtures
+
+- `tests/fixtures/repo-signals/tink-harness.json`: stable repo facts such as sync groups, instruction files, schema files, command surface, and verification hints.
+- `tests/fixtures/repo-signals/path-cases.json`: examples of changed paths and the verification hints they should select.
+- `tests/fixtures/current-run/context-map.json`: an example of context signals that cite repo signal sources.
+- `tests/fixtures/current-run/contract.json`: an example of selected verification hints written as manual checks.
+
+## Flow
+
+The intended cast flow is:
+
+```text
+changed path
+-> matching context_graph_lite rules
+-> small related context set
+-> matching repo signal verification_hints
+-> contract.verification.manual_checks[]
+-> context-map.json signals
+```
+
+For example:
+
+```text
+commands/cast.md
+-> context_graph_lite.rules.claude-command-sync
+-> include matching command copies and tests/test_templates.py
+-> verification_hints.command-template-sync
+-> manual check: test_dual_format_paths_stay_in_sync
+-> context-map signal: verification_hint
+```
+
+The contract records what must be checked. The context map records why that check was selected.
+
+## Unmatched Paths
+
+If a changed path matches no verification hint, Tink should not invent a check.
+
+Instead, it records an `unmatched_path` signal in `context-map.json`.
+
+Example:
+
+```text
+docs/memory.md
+-> no matching verification hint
+-> no manual check added
+-> context-map signal: unmatched_path
+```
+
+This keeps Tink honest. Unknown context is still visible, but it does not create fake certainty.
+
+## Boundaries
+
+Repo signal fixtures are advisory inputs.
+
+They must not:
+
+- run commands;
+- install tools;
+- write files;
+- create command surfaces;
+- behave like a runtime indexer.
+
+If runtime support is added later, it should preserve the same contract: signals explain context and verification choices, while checks still run through the normal verification flow.

package/docs/research.md

@@ -0,0 +1,16 @@
+# Research notes
+
+Tink was shaped by a small survey of harness, agent, workflow, and skill projects. The survey goal was to learn invariants, not copy implementations.
+
+## Borrowed principles
+
+- Small composable skills reduce setup friction.
+- Feedback loops are the speed limit.
+- Handoffs and guardrails should be explicit.
+- State and recovery matter, but a full workflow engine is too heavy for Tink v0.
+- Verification should happen before completion claims.
+- Repeated mistakes should become short reusable rules after approval.
+
+## Product decision
+
+Tink v0 is Claude Code-only. This keeps the first version easy to understand and install.

package/docs/tink-idea-implementation-plan.ko.md

@@ -0,0 +1,201 @@
+# Tink 아이디어 구현 점검과 다음 계획
+
+이 문서는 지금까지 논의한 Tink 확장 아이디어가 v1.2.x 기준으로 어디까지 구현되었는지 점검하고, 다음에 어떤 순서로 확장하면 좋은지 정리한다.
+
+핵심 방향은 그대로 유지한다. Tink는 자체 거대 런타임이 아니라 Claude Code와 Codex 위에 얹는 경량 하네스 계층이다. 목표는 더 많은 명령을 만드는 것이 아니라, 작업 전 context 설계, 작업 계약, 검증 가능한 완료, 반복 개선을 더 안정적으로 만드는 것이다.
+
+## 요약
+
+v1.2.0에서 가장 크게 들어간 것은 Codex 지원, context artifact, Repo Signal, Verify Runner, MCP Safe Profile의 기반이다. 즉, Tink가 단순한 명령 묶음에서 "작업 상태와 검증 계약을 남기는 하네스 레이어"로 이동하기 시작했다.
+
+다만 첨부 아이디어에서 말한 완전한 graph 기반 context compiler, 실제 MCP gateway, productivity dashboard, harness registry, subagent adapter는 아직 구현되지 않았다. 지금 단계에서는 이들을 한 번에 크게 만들기보다, 현재 surface를 유지한 채 내부 artifact와 검증 품질을 조금씩 강화하는 편이 맞다.
+
+중요한 제약도 명확하다.
+
+- Claude Code와 Codex를 모두 지원한다.
+- macOS와 Windows를 모두 지원한다.
+- 새 public `tink index` command는 만들지 않는다.
+- Sentry 연동은 현재 계획에서 제외한다.
+- 문서는 한국어로도 제공한다.
+- 사용자 수정 파일, local memory, local harness는 update 과정에서 보존한다.
+
+## 구현 상태 매트릭스
+
+| 아이디어 | 현재 상태 | 구현된 부분 | 아직 필요한 부분 |
+| --- | --- | --- | --- |
+| Codex/Claude Code 동시 지원 | 상당 부분 구현 | Codex action skills, Claude Code commands, installer surface 선택, focused Codex picker, compatibility policy | update 결과 요약, 기존 설치 진단, 양쪽 surface를 함께 검증하는 recipe 강화 |
+| Contract-first execution | 구현 기반 있음 | `.tink/current/contract.json`, verification command/manual check schema, success/risk/evidence 구조 | 실제 작업 중 contract 변경 이력, diff evidence 연결, blocked 복구 흐름 강화 |
+| Context Pack / Context Map | 부분 구현 | `context-pack.md`, `context-map.json`, `excluded-context.md`, external context profile, repo signal fixture | 실제 dependency graph 분석, changed path 기반 context 선택 고도화, 왜 제외했는지의 품질 개선 |
+| Repo Signals | 부분 구현 | fixture 기반 instruction files, schema files, verification hints, sync groups | 내부 Context Graph Lite로 확장, 테스트/문서/명령 연결 자동 추론, confidence 점수 개선 |
+| Verify Runner | 부분 구현 | `verification.json`, pass/fail/blocked/skipped, final report, notes summary, maintenance signals | command 실행 증거 요약, diff/coverage/security/manual evidence 연결, 재실행 recipe 자동화 |
+| MCP Safe Profile | 문서와 schema 기반 있음 | 외부 context 안전 체크리스트, sensitivity/confidence/source_ref, Figma/GitHub/docs 예시 | 실제 `.tink/mcp-policy.json`, allowlist, read-only 기본값, secret redaction, prompt injection scanner |
+| Hook 기반 safety | 일부 구현 | advisory-only `UserPromptSubmit` hook 추천 | PreToolUse/PostToolUse/Stop/PreCompact에 대응하는 안전 profile 설계, 승인된 경우에만 guard화 |
+| Productivity dashboard | 미구현 | ledger/friction/weave queue로 원천 신호는 있음 | token/context cost, 실패 유형, 검증 누락, update 이슈를 사람이 읽기 쉬운 요약으로 변환 |
+| Harness 자동 개선과 삭제 | 부분 구현 | `/tink:weave`, `/tink:frog`, evidence grade, maintenance ledger | 사용 빈도와 실패 신호 기반 scoring, 삭제/병합 후보 설명 품질, 승인 전 preview |
+| Harness registry/signing/lockfile | 미구현 | plugin/package release 흐름은 있음 | `.tink/lock.json`, registry metadata, source trust, version pinning |
+| Subagent adapter | 미구현 | multi-agent 자체 런타임을 만들지 않는 방향만 정해짐 | Claude/Codex의 기존 subagent 기능에 맞춘 얇은 adapter contract |
+| Memory knowledge layers | 부분 구현 | `.tink/memory/`, reusable save gate | `approved/`, `candidate/`, `rejected/`, `evidence/` 계층화와 승인 이력 |
+
+## 다음 구현 원칙
+
+### 1. 새 명령보다 기존 흐름 강화
+
+첨부 아이디어에는 `tink index` 같은 graph 명령이 있었지만, 이 프로젝트에서는 새 public command를 만들지 않는다. 대신 `$tink:cast`와 `/tink:cast` 내부에서 context selection 품질을 높인다.
+
+이름은 "Context Graph Lite" 정도로 문서화하되, 사용자는 새 명령을 외우지 않아도 된다.
+
+### 2. artifact를 먼저 안정화
+
+큰 기능을 바로 자동화하기 전에 다음 파일들의 의미를 더 안정적으로 만든다.
+
+- `.tink/current/context-pack.md`
+- `.tink/current/context-map.json`
+- `.tink/current/excluded-context.md`
+- `.tink/current/contract.json`
+- `.tink/current/verification.json`
+- `.tink/maintenance/ledger.jsonl`
+- `.tink/maintenance/friction.jsonl`
+
+Tink의 장점은 "AI가 알아서 했다"가 아니라 "왜 이 context와 검증을 선택했는지 확인할 수 있다"에 있다.
+
+### 3. 모든 확장은 양쪽 surface와 양쪽 OS를 기준으로 설계
+
+새 기능은 Claude Code command와 Codex skill에서 같은 개념으로 설명되어야 한다. 또한 shell 예시, path, installer/update 동작은 macOS와 Windows 모두에서 자연스럽게 동작해야 한다.
+
+## 제안 로드맵
+
+### Phase 5: Update Confidence
+
+기존 사용자가 v1.2.x로 업데이트할 때 무엇이 바뀌고 무엇이 보존되는지 확신할 수 있게 만든다.
+
+생기는 기능:
+
+- update 후 설치된 surface 요약
+- refresh된 command/skill 목록
+- 제거된 legacy Codex `skills/tink/SKILL.md` 표시
+- 보존된 user-modified files 표시
+- 다음에 실행할 검증 command 안내
+
+개선 효과:
+
+- 기존 사용자가 update 후 Codex picker나 Claude command 상태를 덜 헷갈린다.
+- update가 local harness, memory, config를 건드렸는지 확인하기 쉬워진다.
+- 이후 큰 기능을 넣기 전에 업데이트 안정성을 먼저 확보한다.
+
+### Phase 6: Context Graph Lite
+
+새 public command 없이 `$tink:cast`와 `/tink:cast`가 내부적으로 더 나은 context 후보를 고르게 만든다.
+
+생기는 기능:
+
+- changed paths를 기준으로 관련 tests, schemas, docs, command copies를 더 잘 찾는다.
+- sync group이나 verification hint가 왜 선택됐는지 `context-map.json.signals[]`에 더 구체적으로 남긴다.
+- 제외한 파일은 `excluded-context.md`에 "왜 제외했는지"를 짧게 남긴다.
+
+개선 효과:
+
+- context pack이 더 작고 정확해진다.
+- Codex와 Claude Code 모두 같은 판단 근거를 공유한다.
+- `tink index` 같은 별도 명령 없이도 graph 느낌의 도움을 받을 수 있다.
+
+### Phase 7: Evidence Runner Plus
+
+검증 결과를 더 행동 가능한 증거로 만든다.
+
+생기는 기능:
+
+- command evidence, manual evidence, diff evidence를 구분한다.
+- 실패한 check마다 `next_action`을 더 명확히 기록한다.
+- blocked 상태일 때 마지막 안전 지점과 재개 방법을 더 잘 남긴다.
+
+개선 효과:
+
+- 검증 실패가 단순한 "실패"가 아니라 다음 행동으로 이어진다.
+- PR/release history에 들어갈 검증 근거가 더 깔끔해진다.
+- weave가 반복 실패를 더 정확하게 개선 후보로 받을 수 있다.
+
+### Phase 8: MCP Gateway Policy
+
+외부 context를 가져올 때의 안전 기준을 실제 정책 파일로 만든다. Sentry는 현재 제외하고, Figma, GitHub, official docs, dashboard, attachment 같은 일반 source를 우선한다.
+
+생기는 기능:
+
+- `.tink/mcp-policy.schema.json`
+- optional `.tink/mcp-policy.json`
+- source allowlist
+- read-only 기본값
+- secret/sensitive context redaction 규칙
+- prompt injection 의심 문구를 evidence에 남기는 규칙
+
+개선 효과:
+
+- 외부 context를 더 많이 쓰더라도 안전 기준이 흐려지지 않는다.
+- "가져온 정보"와 "신뢰해도 되는 정보"를 분리할 수 있다.
+- 회사/개인 프로젝트에서 source별 정책을 조정하기 쉬워진다.
+
+### Phase 9: Harness Lifecycle Metrics
+
+하네스가 실제로 도움이 되는지, 오래되어 정리해야 하는지 판단할 수 있게 만든다.
+
+생기는 기능:
+
+- harness별 사용 신호 요약
+- 반복 실패와 반복 성공 신호
+- context-cost 증가 신호
+- frog/weave 후보 목록
+- 삭제, 병합, 유지 추천 이유
+
+개선 효과:
+
+- Tink가 하네스를 무작정 늘리지 않는다.
+- 실제 도움이 된 하네스와 헷갈리게 만드는 하네스를 구분한다.
+- `/tink:frog`가 더 설득력 있는 정리 제안을 할 수 있다.
+
+### Phase 10: Memory Knowledge Layers
+
+메모리를 "승인된 지식"과 "후보"로 분리한다.
+
+생기는 기능:
+
+- `.tink/memory/approved/`
+- `.tink/memory/candidate/`
+- `.tink/memory/rejected/`
+- `.tink/memory/evidence/`
+
+개선 효과:
+
+- 한 번 나온 말이 곧바로 영구 규칙이 되는 위험을 줄인다.
+- 사용자 승인 전에는 candidate로만 남긴다.
+- 왜 어떤 기억이 저장되었는지 evidence를 추적할 수 있다.
+
+## 더 추가하면 좋은 아이디어
+
+### Context Diff Review
+
+작업 시작 전후로 context-map이 어떻게 달라졌는지 비교한다. 예를 들어 처음에는 빠졌지만 작업 중 필요해진 파일, 처음에는 포함했지만 실제로는 쓰지 않은 파일을 기록한다.
+
+이 기능은 Context Graph Lite와 Harness Lifecycle Metrics 사이를 이어준다.
+
+### Update Doctor
+
+`update` 결과가 이상할 때 사람이 바로 확인할 수 있는 체크리스트를 제공한다. 새 명령을 만들기보다 `$tink:update`와 `/tink:update` 문서 안에 "진단 모드" 절차로 넣는다.
+
+## 제외한 아이디어
+
+### Release Evidence Pack
+
+release나 PR 작업이 끝났을 때 `contract.json`, `verification.json`, changelog, npm pack 결과, GitHub release 상태를 하나의 요약으로 묶는 아이디어는 현재 계획에서 제외한다.
+
+이 기능은 릴리즈 판단, 공개 기록, 포트폴리오성 서술까지 Tink가 지나치게 많이 제안하게 만들 수 있다. 그 영역은 사용자나 팀이 직접 결정해야 하므로, Tink는 필요한 검증 artifact를 남기는 선에서 멈춘다.
+
+## 바로 다음 Slice 추천
+
+다음 slice는 Phase 5의 "Update Result Summary"가 가장 좋다.
+
+이유:
+
+- 이미 update smoke test가 있으므로 실패를 잡을 안전망이 있다.
+- 기존 사용자에게 바로 체감되는 개선이다.
+- 이후 Context Graph Lite나 MCP Gateway처럼 더 큰 기능을 넣기 전에 update 신뢰도를 확보할 수 있다.
+
+그 다음에는 Phase 6 "Context Graph Lite"로 넘어가는 흐름을 추천한다. 이때도 새 `tink index` command는 만들지 않고, cast의 내부 context selection과 artifact 품질을 개선하는 방향으로 진행한다.

package/docs/update-diagnosis.ko.md

@@ -0,0 +1,16 @@
+# 업데이트 진단
+
+업데이트 진단은 새 command를 추가하지 않고 update 문제를 더 쉽게 확인하기 위한 흐름이다.
+
+이 흐름은 `/tink:update`, `$tink:update`, troubleshooting 문서, verification recipe 안에서 사용한다.
+
+확인할 항목은 다음과 같다.
+
+- 기대한 install surface: Claude Code, Codex, 또는 둘 다
+- 실제 command와 skill 파일
+- 보존된 user-modified file
+- 제거된 legacy Codex skill 경로
+- 누락된 schema 또는 maintenance file
+- 최종 `Update Result Summary`
+
+다음 행동은 보통 `docs/update-verification-recipe.ko.md` 또는 `docs/update-troubleshooting.ko.md` 같은 가장 작은 recipe로 안내한다.

package/docs/update-diagnosis.md

@@ -0,0 +1,16 @@
+# Update Diagnosis
+
+Update diagnosis makes update problems easier to inspect without adding a new command.
+
+Use it inside `/tink:update`, `$tink:update`, troubleshooting docs, and verification recipes.
+
+Check:
+
+- expected install surface: Claude Code, Codex, or both
+- actual command and skill files
+- preserved user-modified files
+- removed legacy Codex skill paths
+- missing schema or maintenance files
+- final `Update Result Summary`
+
+The next action should point to the smallest useful recipe, usually `docs/update-verification-recipe.md` or `docs/update-troubleshooting.md`.

package/docs/update-troubleshooting.ko.md

@@ -0,0 +1,113 @@
+# 업데이트 문제 해결 가이드
+
+이 문서는 `tink-harness update` 이후 뭔가 오래된 상태처럼 보이거나, 설치 결과가 예상과 다를 때 확인할 항목을 정리한다.
+
+README에는 긴 문제 해결 내용을 넣지 않는다. 평소에는 설치와 사용 흐름을 가볍게 유지하고, 문제가 생겼을 때만 이 문서를 본다.
+
+## 먼저 볼 것
+
+`tink-harness update`가 끝나면 출력의 `Update Result Summary`를 먼저 확인한다.
+
+- `Surfaces`: 새로 고친 대상이 `claude`, `codex`, 또는 `all`인지 확인한다.
+- `Updated or added`: 새 command, skill, schema가 들어갔는지 확인한다.
+- `Preserved user-modified files`: 사용자가 고친 파일이 보존됐는지 확인한다.
+- `Removed legacy paths`: 오래된 Codex `skills/tink` 같은 legacy path가 제거됐는지 확인한다.
+- `Installed locations`: 실제 파일이 들어간 위치를 확인한다.
+
+## Codex skill picker에 예전 `tink`가 보일 때
+
+가능한 원인:
+
+- 이전 버전의 넓은 Codex `skills/tink/SKILL.md`가 남아 있다.
+- `CODEX_HOME`이 예상한 위치와 다르다.
+- Codex UI가 아직 skill 목록을 새로 읽지 않았다.
+
+확인:
+
+```bash
+npx tink-harness@latest update --yes
+```
+
+그 다음 `Update Result Summary`에서 다음을 본다.
+
+- `Codex target`
+- `Removed legacy paths`
+- `Codex skills`
+
+기대 상태:
+
+- `skills/tink`는 없어야 한다.
+- `tink-cast`, `tink-verify`, `tink-list`, `tink-frog`, `tink-weave`, `tink-setup`, `tink-update`가 있어야 한다.
+- `tink-core/RULES.md`는 내부 공유 규칙으로 존재하지만 picker에 action으로 보이지 않는 것이 정상이다.
+
+## schema files가 없을 때
+
+가능한 원인:
+
+- update 대상 surface만 Codex로 맞췄지만 repo `.tink/` 설치 경로가 다르다.
+- update를 다른 working directory에서 실행했다.
+- 기존 사용자 수정 파일이 보존되어 새 템플릿으로 덮이지 않았다.
+
+확인할 파일:
+
+- `.tink/schemas/contract.schema.json`
+- `.tink/schemas/context-map.schema.json`
+- `.tink/schemas/verification.schema.json`
+- `.tink/schemas/session.schema.json`
+
+`Update Result Summary`의 `Install target`이 현재 repo인지 먼저 확인한다.
+
+## 사용자 수정 파일이 덮였는지 걱정될 때
+
+Tink update는 기본적으로 사용자 수정 파일을 보존한다. 특히 local harness, memory, config는 함부로 덮지 않는 것이 원칙이다.
+
+확인:
+
+- `Preserved user-modified files`에 해당 파일이 있는지 본다.
+- `--force`를 쓰지 않았는지 확인한다.
+
+주의:
+
+- `commands`, `skills`, `maintenance` template은 새 버전과 맞추기 위해 update 대상이다.
+- reusable local state는 사용자 승인 없이 새 의미로 바꾸지 않는다.
+
+## Claude Code command가 오래된 것 같을 때
+
+Claude Code command는 세 copy가 같은 내용이어야 한다.
+
+- `commands/<name>.md`
+- `templates/claude/commands/tink/<name>.md`
+- `.claude/commands/tink/<name>.md`
+
+repo 개발 중이라면 다음 검증을 실행한다.
+
+```bash
+npm test
+```
+
+일반 사용자라면 update 후 Claude Code를 다시 열거나 `/reload-plugins`를 실행한다.
+
+## Windows에서 인코딩 경고가 보일 때
+
+Windows PowerShell이나 cp949 환경에서는 일부 테스트 출력에서 인코딩 경고가 보일 수 있다. 테스트가 `OK`로 끝났다면 기존에 알려진 환경 경고일 수 있다.
+
+중요한 기준:
+
+- `npm test`가 성공했는가
+- `node --check bin/install.js`가 성공했는가
+- 실제 파일 내용이 깨진 것이 아니라 terminal 출력만 깨진 것인가
+
+문서 파일은 UTF-8로 저장한다.
+
+## 여전히 이상할 때
+
+다음을 함께 기록하면 다음 진단이 쉬워진다.
+
+- 실행한 update command
+- `Update Result Summary`
+- 사용한 OS
+- `CODEX_HOME` 값
+- 현재 repo path
+- 기대한 surface: Claude Code, Codex, 또는 둘 다
+
+이 정보는 Tink가 자동으로 결정을 대신하기 위한 것이 아니라, 사용자가 어떤 설치 상태인지 빠르게 확인하기 위한 증거다.

package/docs/update-troubleshooting.md

@@ -0,0 +1,100 @@
+# Update Troubleshooting
+
+Use this guide when `tink-harness update` finishes but the installed state still looks stale or incomplete.
+
+README should stay short. This document holds the symptom-specific checks.
+
+## Start Here
+
+After `tink-harness update`, read `Update Result Summary`.
+
+- `Surfaces`: the refreshed target, such as `claude`, `codex`, or `all`.
+- `Updated or added`: commands, skills, and schemas that changed.
+- `Preserved user-modified files`: local files Tink did not overwrite.
+- `Removed legacy paths`: old paths such as Codex `skills/tink`.
+- `Installed locations`: where the files were written.
+
+## Old `tink` Still Appears In Codex
+
+Possible causes:
+
+- The old broad Codex `skills/tink/SKILL.md` is still present.
+- `CODEX_HOME` points somewhere unexpected.
+- Codex has not refreshed the skill list yet.
+
+Run:
+
+```bash
+npx tink-harness@latest update --yes
+```
+
+Then check `Codex target`, `Removed legacy paths`, and `Codex skills` in the summary.
+
+Expected state:
+
+- `skills/tink` is gone.
+- `tink-cast`, `tink-verify`, `tink-list`, `tink-frog`, `tink-weave`, `tink-setup`, and `tink-update` exist.
+- `tink-core/RULES.md` exists as shared internal rules, but should not appear as a user action in the picker.
+
+## Schema Files Are Missing
+
+Check that `Install target` is the repo you meant to update.
+
+Expected schema files:
+
+- `.tink/schemas/contract.schema.json`
+- `.tink/schemas/context-map.schema.json`
+- `.tink/schemas/verification.schema.json`
+- `.tink/schemas/session.schema.json`
+
+If you ran update from a different working directory, run it again from the intended repo.
+
+## Worried About User-Modified Files
+
+By default, update preserves user-modified local harnesses, memory, and config.
+
+Check:
+
+- The file appears under `Preserved user-modified files`.
+- You did not pass `--force`.
+
+Commands, skills, and maintenance templates are refreshed to match the package version. Reusable local state should not change meaning without user approval.
+
+## Claude Code Commands Look Stale
+
+For this repo, command copies must stay in sync:
+
+- `commands/<name>.md`
+- `templates/claude/commands/tink/<name>.md`
+- `.claude/commands/tink/<name>.md`
+
+When developing Tink itself, run:
+
+```bash
+npm test
+```
+
+As a normal user, reload Claude Code or run `/reload-plugins` after updating the plugin.
+
+## Windows Encoding Warnings
+
+On Windows PowerShell or cp949 environments, some command output can show encoding warnings. If tests end with `OK`, this may be an environment warning rather than a failed update.
+
+Useful checks:
+
+- `npm test` passed.
+- `node --check bin/install.js` passed.
+- The file content is UTF-8 and not actually corrupted.
+
+## Still Stuck
+
+Record these details:
+
+- update command used
+- `Update Result Summary`
+- OS
+- `CODEX_HOME`
+- current repo path
+- intended surface: Claude Code, Codex, or both
+
+This evidence helps diagnose install state without letting Tink make release or project decisions on the user's behalf.