tink-harness 1.2.0 → 1.2.2

package/docs/memory-decision-layers.ko.md

@@ -0,0 +1,14 @@
+# 메모리 결정 계층
+
+Tink memory는 결정된 내용과 제안을 분리해야 한다.
+
+설치되는 memory 폴더는 다음과 같다.
+
+- `.tink/memory/approved/`: 로드할 수 있는 승인된 reusable memory.
+- `.tink/memory/candidate/`: 아직 rule처럼 로드하면 안 되는 memory 후보.
+- `.tink/memory/rejected/`: 사용자가 거절했거나 대체한 제안.
+- `.tink/memory/evidence/`: approved memory가 왜 생겼는지 설명하는 짧은 근거 handle.
+
+기존 `mistakes.md`, `preferences.md`, `lessons.md` 파일은 계속 호환된다. 새 흐름에서는 구분이 중요할 때 decision folder를 우선 사용한다.
+
+secret, raw log, full diff, private payload, 일회성 작업 진행 상황은 저장하지 않는다. reusable memory 저장은 항상 별도 승인이 필요하다.

package/docs/memory-decision-layers.md

@@ -0,0 +1,14 @@
+# Memory Decision Layers
+
+Tink memory should separate decisions from suggestions.
+
+Installed memory folders:
+
+- `.tink/memory/approved/`: approved reusable memory that may be loaded.
+- `.tink/memory/candidate/`: possible memory that must not be loaded as a rule yet.
+- `.tink/memory/rejected/`: proposals the user declined or replaced.
+- `.tink/memory/evidence/`: compact handles explaining why approved memory exists.
+
+The older files `mistakes.md`, `preferences.md`, and `lessons.md` remain compatible. Newer workflows should prefer the decision folders when the distinction matters.
+
+Do not store secrets, raw logs, full diffs, private payloads, or one-off task progress. Saving reusable memory always requires separate approval.

package/docs/memory.md

@@ -0,0 +1,31 @@
+# Memory
+
+Tink memory is for preventing repeated frustration.
+
+## Save
+
+- repeated mistakes
+- stable preferences
+- reusable lessons
+
+## Decision layers
+
+- `approved/`: reusable memory that the user explicitly approved and Tink may load.
+- `candidate/`: possible memory that must stay a proposal until approved.
+- `rejected/`: declined or replaced proposals so Tink does not keep asking.
+- `evidence/`: compact evidence handles for approved memory.
+
+The legacy files `mistakes.md`, `preferences.md`, and `lessons.md` remain compatible.
+
+## Do not save
+
+- raw logs
+- full diffs
+- secrets
+- private data
+- one-off task progress
+- stale issue or PR numbers
+
+## Rule
+
+Memory changes require user approval.

package/docs/phase-5-update-confidence.ko.md

@@ -0,0 +1,99 @@
+# Phase 5: 업데이트 신뢰도
+
+Phase 5의 목표는 기존 사용자가 Tink를 업데이트할 때 안전하고, 이해 가능하고, 되돌릴 수 있다고 느끼게 만드는 것입니다.
+
+이 phase는 새 command surface를 추가하는 작업이 아닙니다. 기존 `install`, `update`, `$tink:update`, `/tink:update`, 문서, 검증 흐름을 더 신뢰할 수 있게 만드는 작업입니다.
+
+영어판은 `docs/phase-5-update-confidence.md`에 있습니다.
+
+## 왜 필요한가
+
+v1.2.0은 focused Codex skills, context artifacts, Repo Signals, Verify Runner evidence, MCP Safe Profile guidance를 추가했습니다. 하지만 기존 사용자는 업데이트 후에도 이런 질문을 하게 됩니다.
+
+- update가 예전 Codex `tink` skill을 제거했나?
+- 새 action skills가 설치됐나?
+- 새 schemas가 추가됐나?
+- 내 local harnesses, memory, hooks, config는 보존됐나?
+- 업데이트 후 처음 무엇을 실행하면 되나?
+- 업데이트가 제대로 됐는지 어떻게 확인하나?
+
+Phase 5는 이 질문에 직접 답해야 합니다.
+
+## 목표
+
+- update가 무엇을 바꿨고 무엇을 보존했는지 설명합니다.
+- clean install뿐 아니라 기존 install에 대한 smoke test를 추가합니다.
+- Claude Code와 Codex를 모두 지원합니다.
+- macOS와 Windows에서 모두 동작하게 유지합니다.
+- 명시적으로 always-update 대상인 template이 아니라면 user-modified files를 보존합니다.
+- 넓은 자동화, 숨은 migration, 새 `tink index` command를 추가하지 않습니다.
+
+## 제안 Slice
+
+### Slice 1: 기존 사용자 update smoke tests
+
+다음을 테스트합니다.
+
+- legacy `skills/tink/SKILL.md`가 있는 Codex install이 focused action skills로 업데이트되는지.
+- 오래된 Codex action skill files가 refresh되는지.
+- `context-map.schema.json`, `verification.schema.json` 같은 새 schemas가 추가되는지.
+- user-modified preserved files가 보존되는지.
+- update 후에도 Claude Code command 3-copy 동기화가 유지되는지.
+
+### Slice 2: Update Result Summary
+
+`update` 후 installer output을 개선해서 사용자가 다음을 볼 수 있게 합니다.
+
+- 설치된 surfaces.
+- 업데이트된 command 또는 skill 위치.
+- legacy Codex skill path가 제거됐는지.
+- 보존된 user-modified files.
+- 다음에 실행할 command.
+
+새 state file을 만들지 않고 plain text output으로 시작합니다.
+
+### Slice 3: Troubleshooting Guide
+
+짧은 update troubleshooting section을 추가합니다.
+
+- Codex skill picker에 여전히 old `tink`가 보일 때.
+- plugin update가 latest를 못 찾을 때.
+- schema files가 없을 때.
+- local `.tink/current/` state가 오래됐을 때.
+- Windows shell encoding warning이 테스트 중 보일 때.
+
+### Slice 4: Verification Recipe
+
+작은 검증 recipe를 문서화합니다.
+
+```bash
+npm test
+npx tink-harness@latest update --yes
+```
+
+그 다음 확인할 항목:
+
+- Codex skill directory.
+- Claude command copies.
+- `.tink/schemas/`.
+- `.tink/config.json`.
+- `.gitignore` policy.
+
+## 완료 기준
+
+- 기존 사용자 update tests가 통과합니다.
+- README와 한국어 README가 update confidence path를 설명합니다.
+- `$tink:update`와 `/tink:update` 지침이 update 검증 방법을 언급합니다.
+- 새 public command가 추가되지 않습니다.
+- README가 참조하는 docs가 npm package에 포함됩니다.
+
+## 위험
+
+- user-modified files를 덮어쓰면 신뢰가 깨집니다.
+- update output이 너무 길면 오히려 시끄러워집니다.
+- 한 surface만 테스트하면 Codex와 Claude Code 동작이 갈라질 수 있습니다.
+- shell-specific syntax에 의존하면 Windows와 macOS 동작이 달라질 수 있습니다.
+
+## 추천 첫 단계
+
+기존 사용자 update smoke tests부터 시작합니다. 가장 명확한 안전 신호를 만들고, 이후 output이나 docs 변경이 추측이 아니라 검증 위에 올라가게 해줍니다.

package/docs/phase-5-update-confidence.md

@@ -0,0 +1,97 @@
+# Phase 5: Update Confidence
+
+Phase 5 should make existing users confident that updating Tink is safe, understandable, and reversible.
+
+This phase is not about adding a new command surface. It should improve the existing `install`, `update`, `$tink:update`, `/tink:update`, docs, and verification flow.
+
+## Why This Is Needed
+
+v1.2.0 added focused Codex skills, context artifacts, Repo Signals, Verify Runner evidence, and MCP Safe Profile guidance. Those changes are useful, but existing users may still wonder:
+
+- Did update remove the old Codex `tink` skill?
+- Did it install the new action skills?
+- Did it add the new schemas?
+- Did it preserve my local harnesses, memory, hooks, and config?
+- What should I run first after updating?
+- How do I know the update worked?
+
+Phase 5 should answer those questions directly.
+
+## Goals
+
+- Make update behavior explain what changed and what was preserved.
+- Add smoke tests for existing installs, not only clean installs.
+- Keep update behavior compatible with Claude Code and Codex.
+- Keep update behavior portable across macOS and Windows.
+- Preserve user-modified files unless a template is explicitly in the always-update set.
+- Avoid broad automation, hidden migrations, or a new `tink index` command.
+
+## Proposed Slices
+
+### Slice 1: Existing User Update Smoke Tests
+
+Add test coverage for:
+
+- Codex install with legacy `skills/tink/SKILL.md` updates to focused action skills.
+- Existing stale Codex action skill files are refreshed.
+- New schemas such as `context-map.schema.json` and `verification.schema.json` are added.
+- User-modified preserved files stay preserved.
+- Claude Code command 3-copy behavior remains aligned after update.
+
+### Slice 2: Update Result Summary
+
+Improve installer output after `update` so users can see:
+
+- installed surfaces;
+- updated command or skill locations;
+- removed legacy Codex skill path, when applicable;
+- preserved user-modified files;
+- next command to run.
+
+This should be plain text, not a new state file.
+
+### Slice 3: Troubleshooting Guide
+
+Add a short update troubleshooting section:
+
+- Codex skill picker still shows old `tink`;
+- plugin update does not show latest;
+- schema files are missing;
+- local `.tink/current/` state is stale;
+- Windows shell encoding warning appears during tests.
+
+### Slice 4: Verification Recipe
+
+Document a small verification recipe:
+
+```bash
+npm test
+npx tink-harness@latest update --yes
+```
+
+Then inspect:
+
+- Codex skill directory;
+- Claude command copies;
+- `.tink/schemas/`;
+- `.tink/config.json`;
+- `.gitignore` policy.
+
+## Done Means
+
+- Existing-user update tests pass.
+- README and Korean README explain the update confidence path.
+- `$tink:update` and `/tink:update` guidance mention how to verify an update.
+- No new public command is added.
+- npm package contents still include the docs needed by README.
+
+## Risks
+
+- Overwriting user-modified files would break trust.
+- Too much update output would become noisy.
+- Codex and Claude Code behavior could drift if tests cover only one surface.
+- Windows and macOS shell behavior can diverge if tests rely on shell-specific syntax.
+
+## Preferred First Step
+
+Start with existing-user update smoke tests. They give the clearest safety signal and make later output/docs changes less speculative.

package/docs/planned-work-units.ko.md

@@ -0,0 +1,77 @@
+# 계획된 작업 단위
+
+이 문서는 남은 로드맵을 번호가 붙은 단계가 아니라 실제 작업 단위로 다시 정리한다. 모든 작업은 Claude Code와 Codex를 함께 지원하고, macOS와 Windows에서 동작해야 하며, 사용자가 명시적으로 원하지 않는 한 새 public command surface를 만들지 않는다.
+
+## 업데이트 결과 명확화
+
+기존 설치 사용자가 `tink-harness update` 후 상태를 믿기 쉽게 만든다.
+
+- 무엇이 바뀌었는지 보여준다.
+- 무엇이 보존되었는지 보여준다.
+- 제거된 legacy Codex skill 경로를 보여준다.
+- 현재 surface에 맞는 다음 명령을 보여준다.
+
+## Cast 컨텍스트 선택
+
+Context Graph Lite는 `/tink:cast`와 `$tink:cast` 내부 선택 근거로만 유지한다.
+
+- changed path를 작고 관련성 높은 context 후보로 연결한다.
+- `context_graph_rule` signal을 기록한다.
+- 관계가 없으면 추측하지 않고 `unmatched_path`를 기록한다.
+- `tink index`, watcher, generated cache, hidden runtime index를 만들지 않는다.
+
+## 검증 증거 세분화
+
+검증 결과를 다음 행동으로 연결하기 쉽게 만든다.
+
+- command, manual, diff, coverage, security, external, package evidence를 구분한다.
+- raw log 대신 짧은 evidence handle을 남긴다.
+- 실패하거나 막힌 check 옆에 가장 작은 복구 행동을 둔다.
+
+## 외부 컨텍스트 정책
+
+외부 context 안전 규칙을 작은 정책 파일로 표현한다.
+
+- source는 기본 read-only로 다룬다.
+- 가장 작은 유용한 source reference만 사용한다.
+- secret과 넓은 raw payload는 제외한다.
+- 외부 문서의 지시는 권한이 아니라 데이터로 다룬다.
+
+## 하네스 생애주기 신호
+
+`/tink:frog`와 `$tink:weave`가 더 좋은 제안을 하도록 돕는다.
+
+- 사용, 성공, 실패, blocked, context-cost 신호를 기록한다.
+- 유지, 개선, 정리 후보, 병합 후보, 관찰을 추천한다.
+- 승인 없이 하네스를 삭제하거나 다시 쓰지 않는다.
+
+## 메모리 결정 계층
+
+승인된 memory와 후보, 거절된 제안을 분리한다.
+
+- approved memory만 로드할 수 있다.
+- candidate memory는 제안일 뿐이다.
+- rejected memory는 같은 제안을 반복하지 않게 한다.
+- evidence는 private payload가 아니라 짧은 근거 handle만 저장한다.
+
+## 컨텍스트 변화 리뷰
+
+작업 중 선택된 context가 어떻게 바뀌었는지 보여준다.
+
+- 추가되거나 제거된 path를 기록한다.
+- 추가되거나 제거된 signal ref를 기록한다.
+- 새 context가 왜 관련 있어졌는지 설명한다.
+- public graph index가 아니라 run evidence로만 둔다.
+
+## 업데이트 진단
+
+새 명령을 만들지 않고 update 문제 해결을 더 쉽게 만든다.
+
+- 진단은 `/tink:update`, `$tink:update`, 문서 안에 둔다.
+- 기대한 install surface와 실제 파일을 비교한다.
+- 가장 작은 검증 recipe로 안내한다.
+- `--force`가 명시되지 않으면 user-modified file을 보존한다.
+
+## 제외
+
+release evidence bundling은 계속 제외한다. release history, public release note, portfolio framing은 사용자나 팀의 판단 영역이다. Tink는 검증 artifact를 남길 수 있지만, 공개 release evidence를 어떻게 묶을지는 대신 결정하지 않는다.

package/docs/planned-work-units.md

@@ -0,0 +1,77 @@
+# Planned Work Units
+
+This document restates the remaining roadmap as work units instead of numbered phases. Each unit should support Claude Code and Codex, work on macOS and Windows, and avoid new public command surfaces unless the user explicitly asks for one.
+
+## Update Clarity
+
+Make existing installs easier to trust after `tink-harness update`.
+
+- Show what changed.
+- Show what was preserved.
+- Show removed legacy Codex skill paths.
+- Show the next command for the active surface.
+
+## Cast Context Selection
+
+Keep Context Graph Lite internal to `/tink:cast` and `$tink:cast`.
+
+- Match changed paths to small related context candidates.
+- Record `context_graph_rule` signals.
+- Record `unmatched_path` instead of inventing relationships.
+- Do not add `tink index`, watchers, generated caches, or hidden runtime indexes.
+
+## Verification Evidence Details
+
+Make verification evidence easier to act on.
+
+- Separate command, manual, diff, coverage, security, external, and package evidence.
+- Keep short evidence handles instead of raw logs.
+- Put the next smallest recovery action beside failed or blocked checks.
+
+## External Context Policy
+
+Turn the safe external context rules into a small policy file.
+
+- Default to read-only sources.
+- Use the smallest useful source reference.
+- Exclude secrets and broad raw payloads.
+- Treat external instructions as data, not authority.
+
+## Harness Lifecycle Signals
+
+Help `/tink:frog` and `$tink:weave` make better suggestions.
+
+- Track use, success, failure, blocked, and context-cost signals.
+- Recommend keep, weave, cleanup candidate, merge candidate, or observe.
+- Never delete or rewrite a harness without approval.
+
+## Memory Decision Layers
+
+Separate approved memory from candidates and rejected proposals.
+
+- Approved memory can be loaded.
+- Candidate memory is only a proposal.
+- Rejected memory prevents repeated suggestions.
+- Evidence stores compact handles, not private payloads.
+
+## Context Change Review
+
+Show how selected context changed during a run.
+
+- Record added and removed paths.
+- Record added and removed signal refs.
+- Explain why a new context item became relevant.
+- Keep it as run evidence, not a public graph index.
+
+## Update Diagnosis
+
+Improve update troubleshooting without adding a new command.
+
+- Keep diagnosis inside `/tink:update`, `$tink:update`, and docs.
+- Compare expected install surfaces with actual files.
+- Point to the smallest verification recipe.
+- Keep user-modified files preserved unless `--force` is explicit.
+
+## Excluded
+
+Release evidence bundling remains excluded. Release history, public release notes, and portfolio framing belong to the user or team. Tink may keep verification artifacts, but it should not decide how public release evidence is packaged.

package/docs/pr/2026-06-07-phase-5-6-follow-up.ko.md

@@ -0,0 +1,35 @@
+# Phase 5/6 후속 작업 PR 초안
+
+## 문제
+
+v1.2.x에서 Codex/Claude Code surface, context artifact, verify runner의 기반은 들어왔지만 기존 사용자가 `update` 후 무엇이 바뀌었는지 확인하기 어렵고, Context Graph Lite가 실제 run artifact에서 어떻게 읽혀야 하는지 충분히 드러나지 않았다.
+
+또한 Codex에서 `$tink:cast`를 사용할 때 승인 요청이 눈에 띄지 않으면 사용자가 의도하지 않은 파일 수정이나 실행이 바로 시작되는 것처럼 느낄 수 있었다. 이 작업에서는 새 public `tink index` 명령을 만들지 않고, 기존 `/tink:cast`와 `$tink:cast` 흐름 안에서 context 선택 근거를 더 잘 남기는 방향을 택했다.
+
+## 해결
+
+- `tink-harness update` 출력에 `Update Result Summary`를 추가해 갱신된 파일, 보존된 사용자 수정 파일, 제거된 legacy Codex skill, 설치 위치, 다음 명령을 한 번에 확인할 수 있게 했다.
+- 기존 사용자의 `.tink/config.json`은 `--force` 없이는 보존되도록 update 흐름을 보강했다.
+- Codex `$tink:cast`가 non-trivial run에서 먼저 승인 요청을 보여야 한다는 규칙과 예시를 Codex core rules와 cast skill에 추가했다.
+- Context Graph Lite를 repo signal fixture에 추가하고, changed path가 관련 command copy, Codex skill surface, installer/update docs, schema artifact를 고르는 과정을 테스트로 고정했다.
+- `context-pack.md`, `context-map.json`, `excluded-context.md` fixture가 `context_graph_rule` 신호와 public graph indexing 제외 이유를 보여주도록 보강했다.
+- Work State Guide, Update Troubleshooting, Update Verification Recipe, Repo Signals companion docs를 영어와 한국어로 정리했다.
+- Release Evidence Pack 아이디어는 사용자나 팀의 릴리즈 판단 영역을 침범할 수 있어 현재 계획에서 제외했다.
+
+## 검증
+
+- `npm test`
+  - 33개 테스트 통과
+  - command 3-copy sync, Codex update smoke test, package contents, Context Graph Lite path cases, current-run artifact fixture 확인
+- `git diff --check`
+  - 실패 없음
+  - Windows 줄끝 변환 경고만 출력됨
+- `npm pack --dry-run --json`
+  - 새 문서와 docs/pr 산출물이 패키지에 포함되는 것을 확인
+
+## 참고
+
+- npm publish와 버전 bump는 이번 PR 범위에서 제외했다.
+- Sentry 연동은 사용자의 결정에 따라 포함하지 않았다.
+- 새 `tink index` 명령, watcher, generated cache, hidden runtime index는 추가하지 않았다.
+- 모든 변경은 Claude Code와 Codex, macOS와 Windows 동시 지원을 기준으로 검토했다.