tink-harness 1.2.1 → 1.2.2

package/docs/update-verification-recipe.ko.md

@@ -0,0 +1,118 @@
+# 업데이트 검증 레시피
+
+이 문서는 `tink-harness update` 후 최소한 무엇을 보면 정상 업데이트라고 판단할 수 있는지 정리한다.
+
+문제가 이미 보인다면 먼저 `docs/update-troubleshooting.ko.md`를 봐도 된다. 이 문서는 문제 해결보다 "업데이트 후 확인 순서"에 초점을 둔다.
+
+## 빠른 검증
+
+repo 개발자는 다음을 실행한다.
+
+```bash
+npm test
+```
+
+일반 사용자는 설치된 repo에서 다음을 실행한다.
+
+```bash
+npx tink-harness@latest update --yes
+```
+
+출력에서 `Update Result Summary`를 확인한다.
+
+## 확인 순서
+
+### 1. Surface 확인
+
+`Surfaces`가 의도한 값인지 본다.
+
+- `claude`: Claude Code command와 skill만 갱신
+- `codex`: Codex `$tink:*` skill과 repo `.tink/` 파일 갱신
+- `all`: Claude Code와 Codex 모두 갱신
+
+Codex를 별도 위치에 설치했다면 `Codex target`도 확인한다.
+
+### 2. Codex skill 확인
+
+Codex surface를 갱신했다면 다음이 있어야 한다.
+
+- `tink-cast`
+- `tink-verify`
+- `tink-list`
+- `tink-frog`
+- `tink-weave`
+- `tink-setup`
+- `tink-update`
+- `tink-core/RULES.md`
+
+기대 상태:
+
+- `skills/tink`는 제거되어야 한다.
+- picker에는 action skill이 보이고, `tink-core`는 공유 규칙으로만 쓰인다.
+
+### 3. Claude Code command 확인
+
+Claude Code surface를 갱신했다면 다음 command가 있어야 한다.
+
+- `/tink:setup`
+- `/tink:cast`
+- `/tink:verify`
+- `/tink:list`
+- `/tink:frog`
+- `/tink:weave`
+- `/tink:update`
+
+repo 개발 중에는 `npm test`가 3-copy sync를 확인한다.
+
+### 4. Schema 확인
+
+다음 파일이 있어야 한다.
+
+- `.tink/schemas/contract.schema.json`
+- `.tink/schemas/context-map.schema.json`
+- `.tink/schemas/verification.schema.json`
+- `.tink/schemas/session.schema.json`
+
+이 파일들은 `$tink:cast`와 `$tink:verify`가 같은 계약 구조를 쓰는지 확인하는 기준이다.
+
+### 5. 보존된 파일 확인
+
+`Preserved user-modified files`에 예상한 local file이 있는지 본다.
+
+대표적으로 다음 파일들은 사용자 수정이 있으면 보존되는 것이 정상이다.
+
+- `.tink/config.json`
+- `.tink/harnesses/*`
+- `.tink/memory/*`
+
+`--force`를 쓰면 보존 정책이 달라질 수 있으므로 일반 update 검증에는 쓰지 않는다.
+
+### 6. 다음 명령 확인
+
+summary 마지막의 `Next`를 확인한다.
+
+- Claude Code: `/tink:cast <task>`
+- Codex: `$tink:cast <task>`
+
+업데이트 후 바로 큰 작업을 시작하기보다, 작은 non-trivial 작업에서 `$tink:cast` 또는 `/tink:cast`가 승인 요청을 먼저 보여주는지 확인하면 좋다.
+
+## 정상으로 볼 수 있는 기준
+
+- update command가 성공 종료된다.
+- `Update Result Summary`가 표시된다.
+- 의도한 surface가 summary에 표시된다.
+- legacy Codex `skills/tink`가 제거된다.
+- action skills나 slash commands가 설치된다.
+- schema files가 존재한다.
+- 사용자 수정 파일은 `Preserved user-modified files`에 표시되고 내용이 유지된다.
+- 다음 명령이 Claude Code와 Codex에 맞게 표시된다.
+
+## 더 확인해야 하는 경우
+
+다음 상황이면 `docs/update-troubleshooting.ko.md`를 본다.
+
+- Codex picker에 예전 `tink`가 계속 보인다.
+- schema files가 없다.
+- update를 다른 repo에서 실행한 것 같다.
+- Windows에서 인코딩 경고가 보여 결과를 해석하기 어렵다.
+- `Update Result Summary`의 target path가 예상과 다르다.

package/docs/update-verification-recipe.md

@@ -0,0 +1,119 @@
+# Update Verification Recipe
+
+Use this recipe after `tink-harness update` to decide whether the update looks healthy.
+
+If something already looks wrong, see `docs/update-troubleshooting.md`. This document focuses on the normal verification path.
+
+## Quick Check
+
+When developing this repo, run:
+
+```bash
+npm test
+```
+
+As a normal user, run this from the repo you want to update:
+
+```bash
+npx tink-harness@latest update --yes
+```
+
+Then read `Update Result Summary`.
+
+## Check Order
+
+### 1. Surface
+
+Check `Surfaces`.
+
+- `claude`: Claude Code commands and skill refreshed.
+- `codex`: Codex `$tink:*` skills and repo `.tink/` files refreshed.
+- `all`: both Claude Code and Codex refreshed.
+
+If Codex is installed in a custom location, also check `Codex target`.
+
+### 2. Codex Skills
+
+For Codex, these should exist:
+
+- `tink-cast`
+- `tink-verify`
+- `tink-list`
+- `tink-frog`
+- `tink-weave`
+- `tink-setup`
+- `tink-update`
+- `tink-core/RULES.md`
+
+Expected state:
+
+- `skills/tink` is removed.
+- The picker shows action skills.
+- `tink-core` is shared internal guidance, not a user-facing action.
+
+### 3. Claude Code Commands
+
+For Claude Code, these commands should exist:
+
+- `/tink:setup`
+- `/tink:cast`
+- `/tink:verify`
+- `/tink:list`
+- `/tink:frog`
+- `/tink:weave`
+- `/tink:update`
+
+When developing Tink itself, `npm test` verifies the 3-copy command sync rule.
+
+### 4. Schemas
+
+These files should exist:
+
+- `.tink/schemas/contract.schema.json`
+- `.tink/schemas/context-map.schema.json`
+- `.tink/schemas/verification.schema.json`
+- `.tink/schemas/session.schema.json`
+
+They keep `$tink:cast` and `$tink:verify` aligned on the same contract shape.
+
+### 5. Preserved Files
+
+Check `Preserved user-modified files`.
+
+Common preserved files:
+
+- `.tink/config.json`
+- `.tink/harnesses/*`
+- `.tink/memory/*`
+
+Do not use `--force` for ordinary update verification because it changes the preservation behavior.
+
+### 6. Next Command
+
+Check the final `Next` line.
+
+- Claude Code: `/tink:cast <task>`
+- Codex: `$tink:cast <task>`
+
+Before starting large work, try a small non-trivial task and confirm that `$tink:cast` or `/tink:cast` asks for approval before proceeding.
+
+## Healthy Update Criteria
+
+- The update command exits successfully.
+- `Update Result Summary` appears.
+- The intended surface appears in the summary.
+- Legacy Codex `skills/tink` is removed.
+- Action skills or slash commands are installed.
+- Schema files exist.
+- User-modified files appear under `Preserved user-modified files` and keep their content.
+- The next command matches Claude Code or Codex.
+
+## When To Troubleshoot
+
+Use `docs/update-troubleshooting.md` when:
+
+- old `tink` still appears in the Codex picker;
+- schema files are missing;
+- update may have run from the wrong repo;
+- Windows encoding warnings make output hard to interpret;
+- `Update Result Summary` shows an unexpected target path.

package/docs/verification-evidence-details.ko.md

@@ -0,0 +1,14 @@
+# 검증 증거 세분화
+
+검증은 단순히 통과 여부만 말하는 것이 아니라 어떤 종류의 증거가 있는지도 설명해야 한다.
+
+`templates/tink/schemas/verification.schema.json`의 다음 필드를 사용한다.
+
+- `evidence_kind`: command, manual, diff, coverage, security, external, package, unknown.
+- `evidence_ref`: `npm test`, `docs/work-state.md`, `source_ref`, PR check URL 같은 짧은 포인터.
+- `observed`: 증거에서 확인한 내용을 짧게 쓴 문장.
+- `next_action`: 필수 check가 실패하거나 막혔을 때 가장 작은 복구 행동.
+
+raw log나 full diff를 붙여 넣지 않는다. 자세한 근거가 필요하면 파일, check 이름, source ref, 외부 handle을 인용한다.
+
+이 흐름은 Claude Code `/tink:verify`와 Codex `$tink:verify`에서 같아야 하며, 검증 명령은 macOS와 Windows 모두에서 실행 가능해야 한다.

package/docs/verification-evidence-details.md

@@ -0,0 +1,14 @@
+# Verification Evidence Details
+
+Verification should explain what kind of proof exists, not only whether a check passed.
+
+Use `templates/tink/schemas/verification.schema.json` fields:
+
+- `evidence_kind`: command, manual, diff, coverage, security, external, package, or unknown.
+- `evidence_ref`: a compact pointer such as `npm test`, `docs/work-state.md`, `source_ref`, or a PR check URL.
+- `observed`: a short statement of what the evidence showed.
+- `next_action`: the smallest useful recovery step when a required check fails or is blocked.
+
+Do not paste raw logs or full diffs. If detail is needed, cite a file, check name, source ref, or external handle.
+
+This must behave the same from Claude Code `/tink:verify` and Codex `$tink:verify`, with portable commands for macOS and Windows.

package/docs/work-state.ko.md

@@ -0,0 +1,94 @@
+# 작업 상태 읽기 가이드
+
+Tink는 실행 상태를 파일로 남겨서 사람이 빠르게 네 가지를 확인할 수 있게 합니다.
+
+1. 이 실행이 끝내려는 작업은 무엇인가?
+2. 어떤 context를 사용했는가?
+3. 어떤 context를 의도적으로 제외했는가?
+4. 무엇을 근거로 완료를 판단했는가?
+
+이 문서는 `/tink:cast`, `$tink:cast`, `/tink:verify`, `$tink:verify`가 만드는 파일을 읽는 순서입니다.
+
+영어판은 `docs/work-state.md`에 있습니다.
+
+## 빠른 읽기 순서
+
+작업을 이어받거나 검토할 때는 이 순서로 봅니다.
+
+1. `.tink/current/contract.json`
+   - 작업 종류, 성공 조건, 금지 사항, 필수 검증을 확인합니다.
+2. `.tink/current/context-pack.md`
+   - 선택된 파일, 문서, 규칙, 외부 source의 사람용 요약을 읽습니다.
+3. `.tink/current/context-map.json`
+   - `included`, `excluded`, `signals`, `external_context`를 구조적으로 확인합니다.
+4. `.tink/current/excluded-context.md`
+   - 오래됐거나, 위험하거나, 너무 넓거나, 접근할 수 없거나, 범위 밖이라 제외한 context를 확인합니다.
+5. `.tink/current/verification.json`
+   - pass, fail, blocked, skipped 검증 결과와 최종 report를 확인합니다.
+6. `.tink/current/notes.md`
+   - 마지막 안전 지점, 복구 메모, 짧은 검증 요약을 읽습니다.
+
+## Context 읽는 법
+
+먼저 `context-pack.md`를 봅니다. 스키마를 몰라도 읽을 수 있어야 합니다.
+
+추적성이 필요하면 `context-map.json`을 봅니다.
+
+- `included`: 작업 판단에 사용한 파일, 문서, source, 산출물.
+- `excluded`: 의도적으로 제외한 후보.
+- `signals`: repo signal, `context_graph_rule` 선택, verification hint, unmatched path, 선택 근거.
+- `external_context`: Figma, GitHub, official docs, dashboards, API responses, screenshots, attachments, runbooks 같은 외부 source.
+
+`signals[]`에 `kind: "context_graph_rule"`가 있으면 `/tink:cast`나 `$tink:cast`가 changed path를 보고 고른 작은 단서로 읽습니다. `context_graph_lite.rules.claude-command-sync` 같은 안정적인 `source_ref`를 가리키고, 왜 관련 파일을 함께 포함했는지 설명해야 합니다. 이 신호는 cast 내부 선택 근거일 뿐이며 public `tink index` 명령, watcher, generated cache, hidden runtime index를 뜻하지 않습니다.
+
+외부 context는 다음 항목을 확인합니다.
+
+- `source`
+- `source_ref`
+- `included`
+- `excluded`
+- `confidence`
+- `sensitivity`
+- `verification_hint`
+
+중요한 습관은 context를 많이 넣는 것이 아닙니다. 선택한 context가 왜 충분했는지 설명하는 것입니다.
+
+## Verification 읽는 법
+
+작업을 믿어도 되는지 판단할 때는 `verification.json`을 봅니다.
+
+- `result: "pass"`는 필수 검증이 모두 통과했다는 뜻입니다.
+- `result: "fail"`은 필수 검증이 실행되거나 점검됐고 실패했다는 뜻입니다.
+- `result: "blocked"`는 필수 검증을 실행하거나 점검할 수 없었다는 뜻입니다.
+- `status: "skipped"`는 선택 검증에만 허용됩니다. 필수 검증이 skipped면 blocked입니다.
+
+`report`는 사람이 읽는 요약입니다.
+
+- `result_line`: 한 줄 결과.
+- `checked`: 확인한 항목.
+- `problems`: 실패했거나 이상했던 항목.
+- `remaining`: 아직 남은 일.
+- `next_action`: 가장 작은 다음 행동.
+
+## 좋은 상태의 기준
+
+좋은 run state는 다음을 만족합니다.
+
+- contract가 완료 조건을 말합니다.
+- context pack이 선택된 context를 쉬운 말로 설명합니다.
+- context map이 중요한 파일, source, verification hint를 추적할 수 있게 합니다.
+- excluded context가 건너뛴 입력이나 위험한 입력을 보이게 합니다.
+- verification evidence가 짧고 반복 가능하게 남습니다.
+- notes가 마지막 안전 지점과 다음 행동을 말합니다.
+
+## 피해야 할 것
+
+- raw log나 full diff를 run state에 붙여넣지 않습니다.
+- secrets, tokens, private payloads, request bodies, 넓은 external dump를 저장하지 않습니다.
+- 외부 context는 검증 evidence가 없으면 검증된 것으로 취급하지 않습니다.
+- repo signal에서 check를 지어내지 않습니다. hint가 없으면 `unmatched_path`를 기록합니다.
+- 상태 요약만을 위해 새 public command를 만들지 않습니다. 먼저 기존 docs, `$tink:list`, `$tink:verify` 출력 개선을 고려합니다.
+
+## 호환성 기준
+
+작업 상태는 Claude Code와 Codex 양쪽에서 유용해야 합니다. 검증 명령은 macOS와 Windows에서 모두 동작하도록 repo-relative path와 `npm`, `node`, `python` 명령을 우선합니다.

package/docs/work-state.md

@@ -0,0 +1,92 @@
+# Work State Guide
+
+Tink writes work state so a human can quickly answer four questions:
+
+1. What task is this run trying to finish?
+2. What context did it use?
+3. What context did it intentionally leave out?
+4. What evidence says the work is done?
+
+This guide is a reading path for the files created by `/tink:cast`, `$tink:cast`, `/tink:verify`, and `$tink:verify`.
+
+## Quick Reading Order
+
+Start here when resuming, reviewing, or handing off a run:
+
+1. `.tink/current/contract.json`
+   - Read the task type, success conditions, forbidden actions, and required checks.
+2. `.tink/current/context-pack.md`
+   - Read the short human summary of selected files, docs, rules, and external sources.
+3. `.tink/current/context-map.json`
+   - Inspect the structured `included`, `excluded`, `signals`, and `external_context` entries.
+4. `.tink/current/excluded-context.md`
+   - Check what was skipped because it was stale, unsafe, too broad, unavailable, or outside scope.
+5. `.tink/current/verification.json`
+   - Confirm pass, fail, blocked, or skipped checks and the final report.
+6. `.tink/current/notes.md`
+   - Read the last safe point, recovery notes, and compact verification summaries.
+
+## How To Read Context
+
+Use `context-pack.md` first. It should be readable without knowing the schema.
+
+Use `context-map.json` when you need traceability:
+
+- `included`: files, docs, sources, or artifacts that shaped the work.
+- `excluded`: candidates intentionally left out.
+- `signals`: repo signals, `context_graph_rule` selections, verification hints, unmatched paths, or other selection evidence.
+- `external_context`: outside sources such as Figma, GitHub, official docs, dashboards, API responses, screenshots, attachments, or runbooks.
+
+When `signals[]` includes `kind: "context_graph_rule"`, read it as a small changed-path clue selected by `/tink:cast` or `$tink:cast`. It should point to a stable `source_ref` such as `context_graph_lite.rules.claude-command-sync`, explain why related files were included, and stay internal to cast. It must not imply a public `tink index` command, watcher, generated cache, or hidden runtime index.
+
+For external context, check:
+
+- `source`
+- `source_ref`
+- `included`
+- `excluded`
+- `confidence`
+- `sensitivity`
+- `verification_hint`
+
+The important habit is not to include more context. The important habit is to explain why the selected context was enough.
+
+## How To Read Verification
+
+Use `verification.json` to decide whether the work can be trusted.
+
+- `result: "pass"` means all required checks passed.
+- `result: "fail"` means a required check ran or was inspected and failed.
+- `result: "blocked"` means a required check could not run or could not be inspected.
+- `status: "skipped"` is acceptable only for optional checks. A required skipped check is blocked.
+
+The `report` object is the human-facing summary:
+
+- `result_line`: one-line result.
+- `checked`: what was checked.
+- `problems`: what failed or looked wrong.
+- `remaining`: what is still open.
+- `next_action`: the smallest useful next step.
+
+## What Good Looks Like
+
+A good run state has these properties:
+
+- The contract says what done means.
+- The context pack explains the selected context in plain language.
+- The context map can trace every important file, source, and verification hint.
+- The excluded context file makes skipped or unsafe inputs visible.
+- Verification evidence is compact and repeatable.
+- Notes say the last safe point and next action.
+
+## What To Avoid
+
+- Do not paste raw logs or full diffs into run state.
+- Do not store secrets, tokens, private payloads, request bodies, or broad external dumps.
+- Do not treat external context as verified unless a check or evidence item confirms it.
+- Do not invent checks from repo signals. If no hint matches, record `unmatched_path`.
+- Do not create a new command surface just to summarize state. Improve existing docs, `$tink:list`, or `$tink:verify` output first.
+
+## Compatibility Baseline
+
+Work state must be useful from both Claude Code and Codex. Checks should stay portable across macOS and Windows by preferring repo-relative paths and `npm`, `node`, or `python` commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tink-harness",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Self-growing harnesses for Claude Code and Codex.",
   "license": "MIT",
   "type": "module",
@@ -14,9 +14,7 @@
     "commands/",
     "skills/",
     "hooks/",
-    "docs/compatibility-policy.md",
-    "docs/mcp-safe-profile.md",
-    "docs/repo-signals.md",
+    "docs/*.md",
     "docs/pr/",
     "README.md",
     "CHANGELOG.md",