tink-harness 1.2.2 → 1.4.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tink",
   "description": "A small harness layer for Claude Code and Codex.",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "author": {
     "name": "dotori"
   }

package/CHANGELOG.md

@@ -7,6 +7,41 @@ All notable changes to Tink are tracked here.
 No unreleased changes yet.
 
 
+## [1.4.0] - 2026-06-08
+
+### Added
+
+- `context-metrics-evaluation.schema.json` for `.tink/current/context-metrics-evaluation.json`.
+- Context Metrics Evaluator run-state artifact guidance for `/tink:cast` and `$tink:cast`.
+- Fixture-ratio evaluation docs in Korean and English, explaining measured fixture scope versus production telemetry.
+- Test-backed context metrics evaluation fixture that calculates all six context-efficiency metrics at or above the 90% target within fixture scope.
+- Korean PR history draft for the Context Metrics Artifact work in `docs/pr/2026-06-08-context-metrics-artifact.ko.md`.
+
+### Changed
+
+- Work State Guide now includes `context-metrics-evaluation.json` in the reading order.
+- README and Korean README now link to the Context Metrics Evaluator docs without adding a new command.
+
+
+## [1.3.0] - 2026-06-08
+
+### Added
+
+- Context Budget Ledger fields for `context-map.json` entries: `role`, `cost`, `reuse_signal`, `verification_link`, `staleness`, and `evidence_kind`.
+- `context-map.json.efficiency_metrics` example shape for recording six context-efficiency scores with basis, confidence, evidence refs, and limits.
+- Current-run fixture examples that connect selected context to verification links and mark avoid-next-time exclusions.
+- Repo signal `context_budget_policy` fixture guidance for scoring selected Context Graph Lite candidates without adding a public `tink index` command.
+- Korean-first Context Budget Ledger documentation with an English companion.
+- Korean context-engineering efficiency HTML explainer for the current operating model and expected improvement ranges.
+- Korean PR history draft for the Context Budget Ledger work in `docs/pr/2026-06-08-context-budget-ledger.ko.md`.
+
+### Changed
+
+- `/tink:cast` and `$tink:cast` guidance now asks context artifacts to record role, cost, reuse signal, verification link, staleness, and evidence kind when useful.
+- Work State Guide now explains how to read Context Budget Ledger fields.
+- README and Korean README now link to the Context Budget Ledger docs without expanding the main body.
+
+
 ## [1.2.2] - 2026-06-08
 
 ### Added

package/README.ko.md

@@ -8,7 +8,7 @@ Claude Code와 Codex를 위한 작은 하네스 레이어입니다.
 
 Tink는 지금 작업에 맞는 하네스를 고르고, 실행 상태를 보이게 만들고, 실제 사용 중 생긴 실패와 피드백으로 하네스 세트를 개선합니다.
 
-**최신 릴리스:** v1.2.2 — 업데이트 신뢰도, 작업 단위 계획, 검증 증거 세분화, memory 정책 기반.
+**최신 릴리스:** v1.4.0 — context 효율 점수를 계산식, evidence ref, 측정 scope와 함께 남기는 Context Metrics Evaluator artifact.
 
 [English](README.md) · **한국어**
 
@@ -66,6 +66,7 @@ npx tink-harness@latest update
 - Codex에는 하나의 넓은 `tink` 스킬 대신 `$tink:cast`, `$tink:verify` 같은 action skill만 보이도록 설치됩니다.
 - 비단순 작업은 `context-pack.md`, `context-map.json`, `excluded-context.md`로 어떤 context를 썼고 뺐는지 남깁니다.
 - Repo Signal과 Context Graph Lite는 새 `tink index` 명령을 만들지 않고도 관련 테스트, 스키마, 동기화 파일, 검증 힌트를 고르는 데 쓰입니다.
+- context 효율 점수화와 fixture 비율 계산 기준은 `docs/context-budget-ledger.ko.md`, `docs/context-budget-ledger.md`, `docs/context-metrics-evaluator.ko.md`, `docs/context-metrics-evaluator.md`에서 확인할 수 있습니다.
 - `/tink:verify`와 `$tink:verify`는 같은 Verify Runner 모델을 쓰며 `.tink/current/verification.json`에 검증 증거를 남깁니다.
 - 외부 context는 MCP Safe Profile을 따릅니다. 가장 작은 source handle만 남기고, 신뢰도와 민감도를 표시하며, 위험하거나 너무 넓은 context는 `excluded-context.md`에 따로 기록합니다.
 

package/README.md

@@ -17,14 +17,14 @@
 </p>
 
 <p>
-  <a href="https://github.com/dotoricode/tink-harness/releases/tag/v1.2.2"><img src="https://img.shields.io/github/v/release/dotoricode/tink-harness?label=release&color=2ea44f" alt="GitHub release"></a>
+  <a href="https://github.com/dotoricode/tink-harness/releases/tag/v1.4.0"><img src="https://img.shields.io/github/v/release/dotoricode/tink-harness?label=release&color=2ea44f" alt="GitHub release"></a>
   <a href="https://www.npmjs.com/package/tink-harness"><img src="https://img.shields.io/npm/v/tink-harness?label=npm&color=cb3837" alt="npm version"></a>
   <a href="https://github.com/dotoricode/tink-harness/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/dotoricode/tink-harness/ci.yml?branch=main&label=ci" alt="CI"></a>
   <a href="https://github.com/dotoricode/tink-harness/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dotoricode/tink-harness" alt="License"></a>
   <a href="https://github.com/dotoricode/tink-harness/stargazers"><img src="https://img.shields.io/github/stars/dotoricode/tink-harness?style=social" alt="GitHub stars"></a>
 </p>
 
-<p><strong>Latest release:</strong> v1.2.2 — update confidence, planned work units, evidence details, and memory policy scaffolding.</p>
+<p><strong>Latest release:</strong> v1.4.0 — Context Metrics Evaluator artifact for measured context-efficiency scores.</p>
 
 **English** · [한국어](README.ko.md)
 
@@ -131,6 +131,7 @@ This release makes Tink work as one harness layer across Claude Code and Codex.
 - Codex now installs focused `$tink:*` action skills instead of one broad visible `tink` skill, so the picker shows commands like `$tink:cast` and `$tink:verify` cleanly.
 - Non-trivial runs now create context artifacts: `context-pack.md`, `context-map.json`, and `excluded-context.md`.
 - Repo Signals and Context Graph Lite help `/tink:cast` and `$tink:cast` choose relevant tests, schemas, sync partners, and verification hints without adding a new `tink index` command.
+- Context Budget Ledger fields and fixture-ratio evaluation are documented in `docs/context-budget-ledger.md`, `docs/context-budget-ledger.ko.md`, `docs/context-metrics-evaluator.md`, and `docs/context-metrics-evaluator.ko.md` without adding a new command.
 - `/tink:verify` and `$tink:verify` share one portable Verify Runner model and write compact evidence to `.tink/current/verification.json`.
 - External context now follows the MCP Safe Profile: include only the smallest useful source handle, mark confidence and sensitivity, exclude unsafe context visibly, and connect important claims to verification.
 

package/VERSIONING.md

@@ -1,6 +1,6 @@
 # Versioning
 
-Current version: `1.2.2`
+Current version: `1.4.0`
 
 Tink follows semver from `1.0.0` onward.
 

package/commands/cast.md

@@ -144,6 +144,7 @@ After approval, create `.tink/current/` with these files before doing deeper wor
 - `session.json`: lightweight session metadata, especially rule ids already loaded by phase
 - `context-pack.md`: human-readable selected context, including why each item is relevant
 - `context-map.json`: machine-readable included and excluded context with reasons
+- `context-metrics-evaluation.json`: measured or estimated context-efficiency scores, formulas, evidence refs, and limits
 - `excluded-context.md`: notable omitted files, tools, sources, or claims and why they were excluded
 
 Create `contract.json` before loading harness bodies. It should be short, factual, and based on the user request plus visible project context:
@@ -188,9 +189,12 @@ If `.tink/schemas/session.schema.json` exists, use it as the session shape. Do n
 Create context artifacts before deeper implementation work:
 - `context-pack.md` should name the user task, selected harnesses, contract summary, loaded rules, selected files/docs, selected external sources, and verification implications.
 - `context-map.json` should contain `task`, `included`, `excluded`, `signals`, and `generated_at`. Each included or excluded entry should include `path` or `source`, `kind`, `reason`, and `confidence`. When external context is selected, also write `external_context[]`.
+- When useful, enrich each context entry with Context Budget Ledger fields: `role`, `cost`, `reuse_signal`, `verification_link`, `staleness`, and `evidence_kind`. Use them to explain why the first context pack is small enough, why excluded context should stay out, and which checks prove selected context matters.
+- `context-metrics-evaluation.json` should contain `run`, `evaluator`, `target_threshold_percent`, `measurement_status`, `scope`, `limits`, and `scores[]`. Each score should include `name`, `score_percent`, `formula`, `numerator`, `denominator`, and `evidence_refs`. If the score is based only on fixtures or the current run, say so in `scope` and `limits`; do not claim production-wide 90% without run-history or telemetry evidence.
 - `excluded-context.md` should make important omissions visible, especially files skipped because they are out of scope, stale, risky, too broad, or unverified external claims.
 
 If `.tink/schemas/context-map.schema.json` exists, use it for `context-map.json`. Do not paste the schema into the user response.
+If `.tink/schemas/context-metrics-evaluation.schema.json` exists, use it for `context-metrics-evaluation.json`. Do not paste the schema into the user response.
 
 Use deterministic context selection inside cast. Do not create or require a separate `tink index` command for this phase.
 
@@ -227,6 +231,7 @@ When a repo signal fixture exists, such as `tests/fixtures/repo-signals/*.json`
 - set `signal.source` to the fixture path and `signal.source_ref` to the relevant entry name or JSON path when useful;
 - do not include every fixture entry by default; select only entries that explain the current task, verification, or safety boundary;
 - if the fixture conflicts with live repo state, prefer live repo state and record the fixture mismatch as a medium-confidence signal.
+- if the fixture provides `context_budget_policy`, use it to assign entry roles, cost, reuse signals, verification links, staleness, and evidence kinds; do not treat the policy as telemetry or claim a 90% score without evidence.
 
 Context Graph Lite rules may appear in the same fixture under `context_graph_lite.rules[]`. Use them only inside cast:
 - match changed paths against `when_paths`;
@@ -258,6 +263,7 @@ Exclusion rules:
 - Exclude product phases that are explicitly deferred, and name the deferral in `excluded-context.md`.
 - Prefer a short high-confidence context pack over a broad low-confidence one.
 - When unsure, include the uncertainty in `reason` and set `confidence` to `low` or `medium` rather than silently expanding scope.
+- For repeated false starts, mark the entry with `reuse_signal: "avoid_next_time"` or `role: "stale"` instead of deleting the evidence. This lets later runs skip it faster while preserving the reason.
 
 Candidate limits:
 - Start with 5-12 included entries for normal code/doc work.
@@ -398,7 +404,7 @@ A task is trivial only when ALL of the following are true:
 15. Run Stitch once before committing to `.tink/current/`. If it triggers, show exactly one proposal before approval. Call `AskUserQuestion` as described in the Interaction policy section.
 16. Ask for explicit approval before non-trivial work.
 17. After approval, read only the selected harness files and any approved run-only draft.
-18. Create `.tink/current/` files from the run state contract, including `contract.json`, `session.json`, `context-pack.md`, `context-map.json`, and `excluded-context.md`.
+18. Create `.tink/current/` files from the run state contract, including `contract.json`, `session.json`, `context-pack.md`, `context-map.json`, `context-metrics-evaluation.json`, and `excluded-context.md`.
 19. Execute the first safe step immediately:
    - inspect relevant files,
    - run a read-only diagnostic,

package/docs/context-budget-ledger.ko.md

@@ -0,0 +1,58 @@
+# Context Budget Ledger
+
+Context Budget Ledger는 Tink가 context를 많이 모으는 대신, 왜 넣었고 왜 뺐는지 점수화할 수 있게 만드는 작은 기록 규칙이다.
+
+이 기능은 새 public command가 아니다. `tink index` 명령, watcher, generated cache, hidden runtime index도 만들지 않는다. `/tink:cast`와 `$tink:cast`가 이미 남기는 `context-map.json`과 `context-diff.json`의 항목을 더 읽기 쉽게 만드는 방식이다.
+
+영어판은 `docs/context-budget-ledger.md`에 있다.
+
+## 왜 필요한가
+
+지금의 `context-map.json`은 어떤 파일과 source를 포함하거나 제외했는지 설명할 수 있다. 하지만 반복 작업에서 다음 질문을 정량적으로 답하기에는 정보가 부족했다.
+
+- 이 context가 핵심인가, 보조인가, 검증 대상인가?
+- 처음 context pack에 넣기에는 비용이 높은가?
+- 다음 비슷한 작업에서 다시 불러와야 하는가, 피해야 하는가?
+- 어떤 검증 check와 연결되는가?
+- 오래됐거나 stale한 정보인가?
+
+그래서 context entry에 다음 optional 필드를 추가한다.
+
+- `role`: `primary`, `supporting`, `verification_target`, `external_evidence`, `exclusion_candidate`, `example_only`, `stale`, `avoid_next_time`.
+- `cost`: `low`, `medium`, `high`.
+- `reuse_signal`: `always`, `often`, `rare`, `example_only`, `avoid_next_time`.
+- `verification_link`: 연결되는 check, evidence ref, verification hint.
+- `staleness`: `fresh`, `aging`, `stale`, `unknown`.
+- `evidence_kind`: `file`, `doc`, `schema`, `test`, `command`, `external`, `signal`, `diff`, `unknown`.
+
+## 어떻게 쓰는가
+
+작업 시작 시에는 `role`과 `cost`로 첫 context pack을 작게 고른다.
+
+작업 중에는 새로 필요해진 context를 `context-diff.json`에 남긴다. 이때 `verification_link`가 있으면 리뷰자가 왜 그 파일을 봤는지 다시 추리하지 않아도 된다.
+
+작업 후에는 `reuse_signal`과 `staleness`를 보고 다음 반복에서 제외할 후보를 더 빨리 고른다. 예를 들어 `reuse_signal: "avoid_next_time"`인 외부 research link는 비슷한 로컬-only 작업에서 다시 불러오지 않는다.
+
+`role: "verification_target"`인 항목은 반드시 검증과 연결되어야 한다. 연결이 없으면 검증 누락 후보로 본다.
+
+## 점수화 방식
+
+`context-map.json.efficiency_metrics`는 여섯 지표를 0-100%로 기록한다.
+
+- 불필요 context 포함률 감소: 제외 항목이 `reuse_signal`, `staleness`, 제외 이유를 갖는 비율.
+- 초기 context pack 크기 감소: included 항목이 `role`과 `cost`로 우선순위화되는 비율.
+- 리뷰자가 근거 찾는 시간 감소: included 항목 중 `role`과 `verification_link`가 함께 있는 비율.
+- 검증 누락 탐지율 개선: `verification_target` 항목 중 연결 check가 있는 비율.
+- 반복 작업 context 재사용 정확도: `reuse_signal`이 있는 항목 비율과 path-case 재선택 결과.
+- 재작업 가능성 감소: context-diff에서 뒤늦게 추가된 필수 context와 누락 check가 줄어드는지.
+
+실제 telemetry가 없으면 `measurement_status: "estimated"`로 두고 한계를 함께 적는다. 근거 없이 90% 달성으로 표시하지 않는다.
+
+fixture에서 비율을 계산할 수 있으면 `measurement_status: "measured"`를 쓸 수 있다. 이때도 scope가 fixture인지 production telemetry인지 분명히 적어야 한다. 자세한 계산 기준은 `docs/context-metrics-evaluator.ko.md`를 본다.
+
+## 호환성 기준
+
+- Claude Code와 Codex가 같은 schema와 fixture를 읽는다.
+- macOS와 Windows 모두에서 동작해야 하므로 shell 전용 경로나 OS 전용 명령을 요구하지 않는다.
+- 사용자 승인 없이 reusable memory, harness, rule, config를 저장하지 않는다.
+- Sentry와 release evidence bundling은 포함하지 않는다.

package/docs/context-budget-ledger.md

@@ -0,0 +1,58 @@
+# Context Budget Ledger
+
+Context Budget Ledger is a small record format that helps Tink score why context was included, excluded, reused, or linked to verification.
+
+It is not a new public command. It must not add a `tink index` command, watcher, generated cache, or hidden runtime index. It only enriches the existing `context-map.json` and `context-diff.json` artifacts created by `/tink:cast` and `$tink:cast`.
+
+Korean companion: `docs/context-budget-ledger.ko.md`.
+
+## Why It Exists
+
+The current context map can explain included and excluded context. It needs a little more structure to answer repeated-run questions:
+
+- Is this context primary, supporting, or a verification target?
+- Is it expensive for the first context pack?
+- Should similar future runs reuse it or avoid it?
+- Which check or evidence proves it matters?
+- Is the information fresh or stale?
+
+Context entries can now include optional fields:
+
+- `role`: `primary`, `supporting`, `verification_target`, `external_evidence`, `exclusion_candidate`, `example_only`, `stale`, `avoid_next_time`.
+- `cost`: `low`, `medium`, `high`.
+- `reuse_signal`: `always`, `often`, `rare`, `example_only`, `avoid_next_time`.
+- `verification_link`: related check, evidence ref, or verification hint.
+- `staleness`: `fresh`, `aging`, `stale`, `unknown`.
+- `evidence_kind`: `file`, `doc`, `schema`, `test`, `command`, `external`, `signal`, `diff`, `unknown`.
+
+## How To Use It
+
+At cast time, use `role` and `cost` to keep the first context pack small.
+
+During work, record late-added context in `context-diff.json`. A `verification_link` helps reviewers jump from context to the check that proves it matters.
+
+After work, use `reuse_signal` and `staleness` to exclude weak or stale context faster in the next similar run.
+
+Entries with `role: "verification_target"` should connect to a command, manual check, evidence ref, or verification hint. Missing links are verification omission candidates.
+
+## Scoring
+
+`context-map.json.efficiency_metrics` records the six context-efficiency metrics as 0-100% scores.
+
+- Unnecessary context reduction: excluded entries with reuse and staleness evidence.
+- Initial context pack size reduction: included entries prioritized by role and cost.
+- Reviewer evidence lookup time reduction: included entries with both role and verification_link.
+- Verification omission detection: verification_target entries with matching checks.
+- Repeated context reuse accuracy: entries with reuse_signal and matching path-case reuse.
+- Rework probability reduction: fewer late-added required context entries and missing checks.
+
+If there is no runtime telemetry yet, mark the scores as `measurement_status: "estimated"` and include the limits. Do not claim 90% without evidence.
+
+If fixture ratios can be calculated, `measurement_status: "measured"` is acceptable. The artifact must still state whether the scope is fixture evidence or production telemetry. See `docs/context-metrics-evaluator.md` for the calculation rules.
+
+## Compatibility
+
+- Claude Code and Codex read the same schema and fixtures.
+- macOS and Windows are both supported; no OS-specific shell behavior is required.
+- Reusable memory, harness, rule, and config saves still require explicit approval.
+- Sentry and release evidence bundling are out of scope.

package/docs/context-metrics-evaluator.ko.md

@@ -0,0 +1,39 @@
+# Context Metrics Evaluator
+
+Context Metrics Evaluator는 Context Budget Ledger에 적힌 필드를 실제 비율로 계산하는 테스트 기준이다.
+
+이 기능은 새 public command가 아니다. `tink index` 명령, watcher, generated cache, hidden runtime index를 만들지 않는다. `/tink:cast`와 `$tink:cast`는 `.tink/current/context-metrics-evaluation.json`을 run state artifact로 남기고, `tests/fixtures/current-run/context-metrics-evaluation.json`과 `tests/test_templates.py`는 같은 점수를 계산하는지 확인한다.
+
+영어판은 `docs/context-metrics-evaluator.md`에 있다.
+
+## 왜 필요한가
+
+`context-map.json.efficiency_metrics`에 점수를 사람이 직접 적기만 하면, 숫자가 좋아 보여도 근거가 약하다. Evaluator는 fixture를 다시 읽어서 다음을 계산한다.
+
+- excluded context가 `role`, `cost`, `reuse_signal`, `staleness`, `reason`을 갖는 비율.
+- included context가 `role`과 `cost`를 갖고, high-cost 항목은 `verification_link`를 갖는 비율.
+- included context가 `role`과 `verification_link`를 함께 갖는 비율.
+- `verification_target` 항목이 실제 verification command나 verification hint와 연결되는 비율.
+- 반복 path-case가 expected context role을 갖는 비율.
+- context-diff 변화가 verification link와 metric impact로 추적되는 비율.
+
+## 점수의 의미
+
+`fixture-ratio-v1`에서 90% 이상이라는 말은 “예시 artifact가 내부적으로 측정 가능하고 빠진 필드가 거의 없다”는 뜻이다.
+
+이것은 아직 “실제 모든 사용자 작업에서 90% 효율을 달성했다”는 뜻이 아니다. production telemetry나 여러 run record가 쌓이기 전까지는 scope를 `fixture`로 제한한다.
+
+## 완료 기준
+
+- 여섯 지표가 모두 fixture 계산 기준으로 90% 이상이다.
+- `context-map.json.efficiency_metrics.scores[]`와 `context-metrics-evaluation.json`의 점수가 일치한다.
+- 각 점수에는 `formula`, `numerator`, `denominator`, `evidence_refs`, `limit`가 있다.
+- `measurement_status`는 fixture에서 계산되면 `measured`로 둘 수 있지만, 문서에는 한계를 함께 적는다.
+- 설치된 schema는 `.tink/schemas/context-metrics-evaluation.schema.json`이다.
+
+## 호환성 기준
+
+- Claude Code와 Codex가 같은 artifact를 읽을 수 있어야 한다.
+- macOS와 Windows 모두에서 `npm test`로 검증되어야 한다.
+- 사용자 승인 없이 reusable memory, harness, rule, config를 저장하지 않는다.
+- Sentry와 release evidence bundling은 포함하지 않는다.

package/docs/context-metrics-evaluator.md

@@ -0,0 +1,39 @@
+# Context Metrics Evaluator
+
+Context Metrics Evaluator is a test-backed way to calculate the ratios recorded by Context Budget Ledger.
+
+It is not a new public command. It must not add a `tink index` command, watcher, generated cache, or hidden runtime index. `/tink:cast` and `$tink:cast` write `.tink/current/context-metrics-evaluation.json` as a run-state artifact, and `tests/fixtures/current-run/context-metrics-evaluation.json` plus `tests/test_templates.py` must calculate the same scores.
+
+Korean companion: `docs/context-metrics-evaluator.ko.md`.
+
+## Why It Exists
+
+If `context-map.json.efficiency_metrics` is only hand-written, the numbers can look better than the evidence. The evaluator re-reads the fixtures and calculates:
+
+- Excluded context with `role`, `cost`, `reuse_signal`, `staleness`, and `reason`.
+- Included context with `role` and `cost`, with high-cost entries justified by `verification_link`.
+- Included context with both `role` and `verification_link`.
+- `verification_target` entries linked to known verification commands or hints.
+- Repeated path-cases with expected context roles.
+- Context-diff changes traceable through verification links and metric impacts.
+
+## What The Score Means
+
+In `fixture-ratio-v1`, a score at or above 90% means the example artifacts are internally measurable and have very few missing fields.
+
+It does not mean that every real user run has reached 90% efficiency. Until production telemetry or multiple run records exist, the measurement scope stays `fixture`.
+
+## Done Criteria
+
+- All six metrics are at or above 90% under the fixture calculation.
+- `context-map.json.efficiency_metrics.scores[]` matches `context-metrics-evaluation.json`.
+- Each score has `formula`, `numerator`, `denominator`, `evidence_refs`, and `limit`.
+- `measurement_status` may be `measured` for fixture calculations, but the docs must state the limit.
+- The installed schema is `.tink/schemas/context-metrics-evaluation.schema.json`.
+
+## Compatibility
+
+- Claude Code and Codex read the same artifacts.
+- macOS and Windows are both verified through `npm test`.
+- Reusable memory, harness, rule, and config saves still require explicit approval.
+- Sentry and release evidence bundling are out of scope.

package/docs/pr/2026-06-08-context-budget-ledger.ko.md

@@ -0,0 +1,38 @@
+# Context Budget Ledger
+
+## 문제
+
+Tink는 `context-map.json`과 `excluded-context.md`로 어떤 context를 사용했는지 설명할 수 있었지만, 컨텍스트 엔지니어링 효율을 90% 목표까지 반복 개선하려면 더 정량적인 근거가 필요했다.
+
+특히 다음 항목은 기존 필드만으로는 자동 점검하기 어려웠다.
+
+- 포함한 context가 핵심인지, 보조인지, 검증 대상인지.
+- 처음 context pack에 넣기에는 비용이 높은지.
+- 다음 비슷한 작업에서 재사용해야 하는지, 피해야 하는지.
+- 선택한 context가 어떤 검증 check와 연결되는지.
+- 오래됐거나 stale한 context를 얼마나 빨리 제외할 수 있는지.
+
+## 해결
+
+- `context-map.schema.json`에 `role`, `cost`, `reuse_signal`, `verification_link`, `staleness`, `evidence_kind` 필드를 optional로 추가했다.
+- `context-map.json.efficiency_metrics` 예시를 추가해 여섯 효율 지표를 0-100%와 근거로 기록할 수 있게 했다.
+- current-run fixture와 context-diff fixture에 역할, 비용, 재사용 신호, 검증 연결, metric impact 예시를 추가했다.
+- repo signal fixture에 `context_budget_policy`를 추가해 Context Graph Lite가 선택한 후보를 어떻게 점수화할지 설명했다.
+- `/tink:cast`와 `$tink:cast` 지침에 Context Budget Ledger 필드를 기록하는 규칙을 추가했다.
+- 한국어 우선 문서 `docs/context-budget-ledger.ko.md`와 영어 companion `docs/context-budget-ledger.md`를 추가하고 README에는 링크만 추가했다.
+- 컨텍스트 동작 원리와 정량적 개선 추정치를 설명하는 `docs/context-engineering-efficiency.ko.html`을 repo 문서로 보존했다.
+
+## 검증
+
+- `npm test`
+- `git diff --check`
+- `npm pack --dry-run --json`
+
+## 참고
+
+- 새 public command는 추가하지 않았다. 특히 `tink index` 명령, watcher, generated cache, hidden runtime index를 만들지 않았다.
+- Sentry는 포함하지 않았다.
+- release evidence bundling은 포함하지 않았다.
+- 새 필드는 optional이므로 기존 `context-map.json`을 바로 깨뜨리지 않는다.
+- 실제 telemetry가 없으면 `measurement_status: "estimated"`로 남기고, 근거 없이 90% 달성으로 표시하지 않는다.
+- Claude Code와 Codex, macOS와 Windows 동시 지원을 기준으로 작성했다.

package/docs/pr/2026-06-08-context-metrics-artifact.ko.md

@@ -0,0 +1,30 @@
+# Context Metrics Artifact
+
+## 문제
+
+Context Metrics Evaluator가 fixture 기준으로 여섯 지표를 계산할 수 있게 되었지만, 실제 `/tink:cast`와 `$tink:cast` run state에는 아직 `context-metrics-evaluation.json`이 공식 산출물로 연결되어 있지 않았다. 이 상태에서는 90% 목표를 current run마다 반복 검증하기 어렵다.
+
+## 해결
+
+- `templates/tink/schemas/context-metrics-evaluation.schema.json`을 추가했다.
+- `/tink:cast`와 `$tink:cast` 지침에 `.tink/current/context-metrics-evaluation.json` 생성 규칙을 추가했다.
+- Work State Guide에 metrics evaluation 읽기 순서를 추가했다.
+- Context Metrics Evaluator 문서를 run-state artifact 기준으로 갱신했다.
+- `v1.4.0` 릴리즈 메타데이터, README, CHANGELOG, VERSIONING을 갱신했다.
+
+## 검증
+
+- `npm test`
+- `git diff --check`
+- `claude plugin validate .claude-plugin/plugin.json`
+- `claude plugin validate .claude-plugin/marketplace.json`
+- `npm pack --dry-run --json`
+
+## 참고
+
+- 새 public command는 추가하지 않았다.
+- `tink index` 명령, watcher, generated cache, hidden runtime index를 만들지 않았다.
+- Sentry는 포함하지 않았다.
+- release evidence bundling은 포함하지 않았다.
+- 점수의 scope와 limit를 명시해야 하며, run-history나 telemetry 없이 production-wide 90%를 주장하지 않는다.
+- Claude Code와 Codex, macOS와 Windows 동시 지원을 기준으로 작성했다.

package/docs/pr/2026-06-08-context-metrics-evaluator.ko.md

@@ -0,0 +1,28 @@
+# Context Metrics Evaluator
+
+## 문제
+
+Context Budget Ledger로 context entry에 역할, 비용, 재사용 신호, 검증 연결을 남길 수 있게 되었지만, `efficiency_metrics` 점수는 아직 사람이 적은 값에 가까웠다. 목표 지표를 90% 이상으로 반복 개선하려면 점수가 실제 fixture에서 다시 계산되어야 한다.
+
+## 해결
+
+- `tests/fixtures/current-run/context-metrics-evaluation.json`을 추가해 여섯 지표의 계산식, 분자, 분모, evidence ref를 기록했다.
+- `context-map.json.efficiency_metrics`를 `fixture-ratio-v1` 기준의 `measured` 점수로 갱신했다.
+- `tests/test_templates.py`가 context-map, context-diff, contract, repo signal, path-case fixture를 다시 읽어 점수를 직접 계산하도록 했다.
+- 반복 path-case에 expected context role을 보강해 재사용 정확도도 계산할 수 있게 했다.
+- 한국어 우선 문서 `docs/context-metrics-evaluator.ko.md`와 영어 companion을 추가했다.
+
+## 검증
+
+- `npm test`
+- `git diff --check`
+- `npm pack --dry-run --json`
+
+## 참고
+
+- 새 public command는 추가하지 않았다.
+- `tink index` 명령, watcher, generated cache, hidden runtime index를 만들지 않았다.
+- Sentry는 포함하지 않았다.
+- release evidence bundling은 포함하지 않았다.
+- 이번 점수는 fixture scope의 측정값이며, production telemetry 전체가 90%에 도달했다는 뜻은 아니다.
+- Claude Code와 Codex, macOS와 Windows 동시 지원 기준을 유지했다.

package/docs/work-state.ko.md

@@ -21,11 +21,13 @@ Tink는 실행 상태를 파일로 남겨서 사람이 빠르게 네 가지를
    - 선택된 파일, 문서, 규칙, 외부 source의 사람용 요약을 읽습니다.
 3. `.tink/current/context-map.json`
    - `included`, `excluded`, `signals`, `external_context`를 구조적으로 확인합니다.
-4. `.tink/current/excluded-context.md`
+4. `.tink/current/context-metrics-evaluation.json`
+   - context 효율 점수, 계산식, 분자/분모, evidence ref, 측정 scope와 한계를 확인합니다.
+5. `.tink/current/excluded-context.md`
    - 오래됐거나, 위험하거나, 너무 넓거나, 접근할 수 없거나, 범위 밖이라 제외한 context를 확인합니다.
-5. `.tink/current/verification.json`
+6. `.tink/current/verification.json`
    - pass, fail, blocked, skipped 검증 결과와 최종 report를 확인합니다.
-6. `.tink/current/notes.md`
+7. `.tink/current/notes.md`
    - 마지막 안전 지점, 복구 메모, 짧은 검증 요약을 읽습니다.
 
 ## Context 읽는 법
@@ -39,6 +41,19 @@ Tink는 실행 상태를 파일로 남겨서 사람이 빠르게 네 가지를
 - `signals`: repo signal, `context_graph_rule` 선택, verification hint, unmatched path, 선택 근거.
 - `external_context`: Figma, GitHub, official docs, dashboards, API responses, screenshots, attachments, runbooks 같은 외부 source.
 
+각 context entry에 Context Budget Ledger 필드가 있으면 다음처럼 읽습니다.
+
+- `role`: 이 context가 핵심인지, 보조인지, 검증 대상인지, 다음에는 피해야 하는 후보인지 알려줍니다.
+- `cost`: 처음 context pack에 넣기 위한 상대 비용입니다.
+- `reuse_signal`: 다음 비슷한 작업에서 다시 쓸지, 예시로만 볼지, 피할지 알려줍니다.
+- `verification_link`: 이 context가 어떤 check나 evidence와 연결되는지 보여줍니다.
+- `staleness`: 오래된 정보인지 빠르게 판단하는 신호입니다.
+- `evidence_kind`: 파일, 문서, 스키마, 테스트, 외부 evidence 같은 근거 종류입니다.
+
+자세한 기준은 `docs/context-budget-ledger.ko.md`를 봅니다.
+
+`context-metrics-evaluation.json`은 점수가 어떻게 나왔는지 보여줍니다. `scope: "fixture"`나 `scope: "current_run"`이면 해당 범위 안에서만 측정된 값입니다. 여러 run record나 production telemetry가 없으면 전체 사용자 작업이 90%에 도달했다고 말하지 않습니다.
+
 `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는 다음 항목을 확인합니다.

package/docs/work-state.md

@@ -19,11 +19,13 @@ Start here when resuming, reviewing, or handing off a run:
    - 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`
+4. `.tink/current/context-metrics-evaluation.json`
+   - Check context-efficiency scores, formulas, numerators, denominators, evidence refs, measurement scope, and limits.
+5. `.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`
+6. `.tink/current/verification.json`
    - Confirm pass, fail, blocked, or skipped checks and the final report.
-6. `.tink/current/notes.md`
+7. `.tink/current/notes.md`
    - Read the last safe point, recovery notes, and compact verification summaries.
 
 ## How To Read Context
@@ -37,6 +39,19 @@ Use `context-map.json` when you need traceability:
 - `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 context entries include Context Budget Ledger fields, read them this way:
+
+- `role`: whether the context is primary, supporting, a verification target, or something to avoid next time.
+- `cost`: relative cost for putting the entry in the first context pack.
+- `reuse_signal`: whether similar future runs should reuse, treat as an example, or avoid the entry.
+- `verification_link`: the check, evidence ref, or verification hint connected to the entry.
+- `staleness`: a quick freshness signal.
+- `evidence_kind`: whether the evidence is a file, doc, schema, test, external source, or another kind.
+
+See `docs/context-budget-ledger.md` for the detailed rules.
+
+`context-metrics-evaluation.json` explains how the score was produced. If `scope` is `fixture` or `current_run`, the value is measured only inside that boundary. Do not claim all user work has reached 90% without run-history or production telemetry evidence.
+
 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tink-harness",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Self-growing harnesses for Claude Code and Codex.",
   "license": "MIT",
   "type": "module",

package/templates/claude/commands/tink/cast.md

@@ -144,6 +144,7 @@ After approval, create `.tink/current/` with these files before doing deeper wor
 - `session.json`: lightweight session metadata, especially rule ids already loaded by phase
 - `context-pack.md`: human-readable selected context, including why each item is relevant
 - `context-map.json`: machine-readable included and excluded context with reasons
+- `context-metrics-evaluation.json`: measured or estimated context-efficiency scores, formulas, evidence refs, and limits
 - `excluded-context.md`: notable omitted files, tools, sources, or claims and why they were excluded
 
 Create `contract.json` before loading harness bodies. It should be short, factual, and based on the user request plus visible project context:
@@ -188,9 +189,12 @@ If `.tink/schemas/session.schema.json` exists, use it as the session shape. Do n
 Create context artifacts before deeper implementation work:
 - `context-pack.md` should name the user task, selected harnesses, contract summary, loaded rules, selected files/docs, selected external sources, and verification implications.
 - `context-map.json` should contain `task`, `included`, `excluded`, `signals`, and `generated_at`. Each included or excluded entry should include `path` or `source`, `kind`, `reason`, and `confidence`. When external context is selected, also write `external_context[]`.
+- When useful, enrich each context entry with Context Budget Ledger fields: `role`, `cost`, `reuse_signal`, `verification_link`, `staleness`, and `evidence_kind`. Use them to explain why the first context pack is small enough, why excluded context should stay out, and which checks prove selected context matters.
+- `context-metrics-evaluation.json` should contain `run`, `evaluator`, `target_threshold_percent`, `measurement_status`, `scope`, `limits`, and `scores[]`. Each score should include `name`, `score_percent`, `formula`, `numerator`, `denominator`, and `evidence_refs`. If the score is based only on fixtures or the current run, say so in `scope` and `limits`; do not claim production-wide 90% without run-history or telemetry evidence.
 - `excluded-context.md` should make important omissions visible, especially files skipped because they are out of scope, stale, risky, too broad, or unverified external claims.
 
 If `.tink/schemas/context-map.schema.json` exists, use it for `context-map.json`. Do not paste the schema into the user response.
+If `.tink/schemas/context-metrics-evaluation.schema.json` exists, use it for `context-metrics-evaluation.json`. Do not paste the schema into the user response.
 
 Use deterministic context selection inside cast. Do not create or require a separate `tink index` command for this phase.
 
@@ -227,6 +231,7 @@ When a repo signal fixture exists, such as `tests/fixtures/repo-signals/*.json`
 - set `signal.source` to the fixture path and `signal.source_ref` to the relevant entry name or JSON path when useful;
 - do not include every fixture entry by default; select only entries that explain the current task, verification, or safety boundary;
 - if the fixture conflicts with live repo state, prefer live repo state and record the fixture mismatch as a medium-confidence signal.
+- if the fixture provides `context_budget_policy`, use it to assign entry roles, cost, reuse signals, verification links, staleness, and evidence kinds; do not treat the policy as telemetry or claim a 90% score without evidence.
 
 Context Graph Lite rules may appear in the same fixture under `context_graph_lite.rules[]`. Use them only inside cast:
 - match changed paths against `when_paths`;
@@ -258,6 +263,7 @@ Exclusion rules:
 - Exclude product phases that are explicitly deferred, and name the deferral in `excluded-context.md`.
 - Prefer a short high-confidence context pack over a broad low-confidence one.
 - When unsure, include the uncertainty in `reason` and set `confidence` to `low` or `medium` rather than silently expanding scope.
+- For repeated false starts, mark the entry with `reuse_signal: "avoid_next_time"` or `role: "stale"` instead of deleting the evidence. This lets later runs skip it faster while preserving the reason.
 
 Candidate limits:
 - Start with 5-12 included entries for normal code/doc work.
@@ -398,7 +404,7 @@ A task is trivial only when ALL of the following are true:
 15. Run Stitch once before committing to `.tink/current/`. If it triggers, show exactly one proposal before approval. Call `AskUserQuestion` as described in the Interaction policy section.
 16. Ask for explicit approval before non-trivial work.
 17. After approval, read only the selected harness files and any approved run-only draft.
-18. Create `.tink/current/` files from the run state contract, including `contract.json`, `session.json`, `context-pack.md`, `context-map.json`, and `excluded-context.md`.
+18. Create `.tink/current/` files from the run state contract, including `contract.json`, `session.json`, `context-pack.md`, `context-map.json`, `context-metrics-evaluation.json`, and `excluded-context.md`.
 19. Execute the first safe step immediately:
    - inspect relevant files,
    - run a read-only diagnostic,

package/templates/codex/skills/tink-core/RULES.md

@@ -31,7 +31,7 @@ Accept legacy `$tink <action>` spelling for compatibility, but present `$tink:<a
 11. Use `request_user_input` for choice prompts when available. Otherwise stop and ask one concise blocking approval question directly in chat. Do not continue until the user answers.
 12. Treat reusable saves as a separate hard approval gate for `.tink/memory/*`, `.tink/harnesses/*`, `.tink/rules/*`, `.tink/config.json`, Codex skill files, and template/plugin files that affect future installs.
 13. Current-run approval never authorizes reusable-state writes. Before saving reusable state, show operation, destination files, exact entry or patch summary, reusable reason, sensitive content excluded, and rollback/removal path.
-14. After approval, create `.tink/current/plan.md`, `checks.md`, `steps.json`, `notes.md`, `answers.md`, `contract.json`, `session.json`, `context-pack.md`, `context-map.json`, and `excluded-context.md`.
+14. After approval, create `.tink/current/plan.md`, `checks.md`, `steps.json`, `notes.md`, `answers.md`, `contract.json`, `session.json`, `context-pack.md`, `context-map.json`, `context-metrics-evaluation.json`, and `excluded-context.md`.
 15. Do not stop at recommendation. Execute the first safe step after run state exists.
 16. Run `$tink:verify` behavior before final when `contract.json` lists required checks.
 17. Store reusable memory or rule updates under `.tink/` only after separate approval.
@@ -102,11 +102,16 @@ Create run state before deeper work:
 - `session.json`: loaded rule ids by phase and lightweight retrieval metadata
 - `.tink/current/context-pack.md`: human-readable selected context and why it matters
 - `.tink/current/context-map.json`: machine-readable included/excluded context and reasons
+- `.tink/current/context-metrics-evaluation.json`: measured or estimated context-efficiency scores, formulas, evidence refs, and limits
 - `.tink/current/excluded-context.md`: notable omitted context and why it was left out
 
+When useful, enrich `context-map.json.included[]` and `context-map.json.excluded[]` entries with Context Budget Ledger fields: `role`, `cost`, `reuse_signal`, `verification_link`, `staleness`, and `evidence_kind`. Use them to keep the first context pack small, mark stale or avoid-next-time context, and connect `verification_target` entries to command checks, manual checks, evidence refs, or verification hints. Do not claim any 90% efficiency score without measurement evidence.
+
+When writing `context-metrics-evaluation.json`, include `run`, `evaluator`, `target_threshold_percent`, `measurement_status`, `scope`, `limits`, and `scores[]`. Each score should include `name`, `score_percent`, `formula`, `numerator`, `denominator`, and `evidence_refs`. If the score comes only from fixture or current-run evidence, record that scope and do not claim production-wide 90% without run-history or telemetry evidence.
+
 When external context is needed for `$tink:cast`, write it through the MCP Safe Profile shape in `context-map.json.external_context[]`. Record `source`, `source_ref`, `kind`, `included`, `excluded`, `reason`, `confidence`, `sensitivity`, and `verification_hint` when useful. Treat Figma, GitHub, and official docs as representative examples, not the only supported sources; Linear, Jira, Supabase, dashboards, API responses, screenshots, attachments, and runbooks can follow the same shape.
 
-When repo signal fixtures contain `context_graph_lite.rules[]`, use those rules inside `$tink:cast` to choose the first related context candidates. Match changed paths against `when_paths`, consider `include_paths`, cite selected rules as `context_graph_rule` signals with `source_ref: "context_graph_lite.rules.<name>"`, and connect `signal_refs` to verification hints where relevant. Do not create a public `tink index` command, watch process, generated cache, or hidden runtime index.
+When repo signal fixtures contain `context_graph_lite.rules[]`, use those rules inside `$tink:cast` to choose the first related context candidates. Match changed paths against `when_paths`, consider `include_paths`, cite selected rules as `context_graph_rule` signals with `source_ref: "context_graph_lite.rules.<name>"`, and connect `signal_refs` to verification hints where relevant. If the fixture provides `context_budget_policy`, use it to assign roles, costs, reuse signals, verification links, staleness, and evidence kinds. Do not create a public `tink index` command, watch process, generated cache, or hidden runtime index.
 
 External context safety checklist:
 - Select the smallest useful `source_ref`; avoid whole files, boards, dashboards, logs, or design systems when one issue, frame, section, screenshot, or attachment is enough.

package/templates/tink/schemas/context-map.schema.json

@@ -1,154 +1,247 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dotoricode/tink-harness/schemas/context-map.schema.json",
-  "title": "Tink current run context map",
-  "type": "object",
-  "required": ["task", "included", "excluded", "signals", "generated_at"],
-  "properties": {
-    "task": {
-      "type": "object",
-      "required": ["summary"],
-      "properties": {
-        "summary": {
-          "type": "string",
-          "description": "Short description of the active user task."
-        },
-        "type": {
-          "type": "string",
-          "description": "Task class from contract.json when available."
-        },
-        "harnesses": {
-          "type": "array",
-          "items": { "type": "string" }
-        }
-      },
-      "additionalProperties": true
-    },
-    "included": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/context_entry" }
-    },
-    "excluded": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/context_entry" }
-    },
-    "signals": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["kind", "value", "reason"],
-        "properties": {
-          "kind": { "type": "string" },
-          "value": { "type": "string" },
-          "reason": { "type": "string" },
-          "source": {
-            "type": "string",
-            "description": "Optional source artifact for this signal, such as a repo signal fixture or current run file."
-          },
-          "source_ref": {
-            "type": "string",
-            "description": "Optional path-like reference inside the source artifact."
-          },
-          "confidence": {
-            "type": "string",
-            "enum": ["low", "medium", "high"]
-          }
-        },
-        "additionalProperties": true
-      }
-    },
-    "external_context": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/external_context_profile" }
-    },
-    "generated_at": {
-      "type": "string",
-      "description": "ISO timestamp for when the context map was created."
-    }
-  },
-  "$defs": {
-    "context_entry": {
-      "type": "object",
-      "required": ["kind", "reason", "confidence"],
-      "oneOf": [
-        { "required": ["path"] },
-        { "required": ["source"] }
-      ],
-      "properties": {
-        "path": {
-          "type": "string",
-          "description": "Repo-local file or directory path."
-        },
-        "source": {
-          "type": "string",
-          "description": "External source, tool, connector, or non-file context."
-        },
-        "kind": {
-          "type": "string",
-          "description": "file, directory, doc, rule, memory, external, command, or other context kind."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why this context was included or excluded."
-        },
-        "confidence": {
-          "type": "string",
-          "enum": ["low", "medium", "high"]
-        },
-        "source_ref": {
-          "type": "string",
-          "description": "Optional source-local reference, such as issue id, frame id, URL label, or attachment name."
-        },
-        "sensitivity": {
-          "type": "string",
-          "enum": ["public", "internal", "sensitive", "secret"]
-        },
-        "verification_hint": {
-          "type": "string",
-          "description": "Follow-up check needed before treating this context as verified."
-        }
-      },
-      "additionalProperties": true
-    },
-    "external_context_profile": {
-      "type": "object",
-      "required": ["source", "source_ref", "kind", "included", "excluded", "reason", "confidence", "sensitivity"],
-      "properties": {
-        "source": {
-          "type": "string",
-          "description": "External source name, such as Figma, GitHub, docs, attachment, dashboard, or another connector."
-        },
-        "source_ref": {
-          "type": "string",
-          "description": "Smallest useful source-local reference."
-        },
-        "kind": {
-          "type": "string",
-          "description": "External context kind, such as error_evidence, design_evidence, work_item, reference, runtime_evidence, or attachment."
-        },
-        "included": {
-          "type": "array",
-          "items": { "type": "string" }
-        },
-        "excluded": {
-          "type": "array",
-          "items": { "type": "string" }
-        },
-        "reason": { "type": "string" },
-        "confidence": {
-          "type": "string",
-          "enum": ["low", "medium", "high"]
-        },
-        "sensitivity": {
-          "type": "string",
-          "enum": ["public", "internal", "sensitive", "secret"]
-        },
-        "verification_hint": { "type": "string" },
-        "blocked_reason": { "type": "string" },
-        "next_action": { "type": "string" }
-      },
-      "additionalProperties": true
-    }
-  },
-  "additionalProperties": true
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dotoricode/tink-harness/schemas/context-map.schema.json",
+  "title": "Tink current run context map",
+  "type": "object",
+  "required": ["task", "included", "excluded", "signals", "generated_at"],
+  "properties": {
+    "task": {
+      "type": "object",
+      "required": ["summary"],
+      "properties": {
+        "summary": {
+          "type": "string",
+          "description": "Short description of the active user task."
+        },
+        "type": {
+          "type": "string",
+          "description": "Task class from contract.json when available."
+        },
+        "harnesses": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "included": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/context_entry" }
+    },
+    "excluded": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/context_entry" }
+    },
+    "signals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "value", "reason"],
+        "properties": {
+          "kind": { "type": "string" },
+          "value": { "type": "string" },
+          "reason": { "type": "string" },
+          "source": {
+            "type": "string",
+            "description": "Optional source artifact for this signal, such as a repo signal fixture or current run file."
+          },
+          "source_ref": {
+            "type": "string",
+            "description": "Optional path-like reference inside the source artifact."
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["low", "medium", "high"]
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "external_context": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/external_context_profile" }
+    },
+    "efficiency_metrics": {
+      "$ref": "#/$defs/efficiency_metrics"
+    },
+    "generated_at": {
+      "type": "string",
+      "description": "ISO timestamp for when the context map was created."
+    }
+  },
+  "$defs": {
+    "context_entry": {
+      "type": "object",
+      "required": ["kind", "reason", "confidence"],
+      "oneOf": [
+        { "required": ["path"] },
+        { "required": ["source"] }
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Repo-local file or directory path."
+        },
+        "source": {
+          "type": "string",
+          "description": "External source, tool, connector, or non-file context."
+        },
+        "kind": {
+          "type": "string",
+          "description": "file, directory, doc, rule, memory, external, command, or other context kind."
+        },
+        "reason": {
+          "type": "string",
+          "description": "Why this context was included or excluded."
+        },
+        "confidence": {
+          "type": "string",
+          "enum": ["low", "medium", "high"]
+        },
+        "role": {
+          "type": "string",
+          "enum": [
+            "primary",
+            "supporting",
+            "verification_target",
+            "external_evidence",
+            "exclusion_candidate",
+            "example_only",
+            "stale",
+            "avoid_next_time"
+          ],
+          "description": "How this entry should be used when building or reviewing the context pack."
+        },
+        "cost": {
+          "type": "string",
+          "enum": ["low", "medium", "high"],
+          "description": "Relative context cost for deciding whether the entry belongs in the first context pack."
+        },
+        "reuse_signal": {
+          "type": "string",
+          "enum": ["always", "often", "rare", "example_only", "avoid_next_time"],
+          "description": "Whether similar future runs should prefer, down-rank, or avoid this context."
+        },
+        "verification_link": {
+          "type": "string",
+          "description": "Check name, evidence ref, or verification hint that proves why this context matters."
+        },
+        "staleness": {
+          "type": "string",
+          "enum": ["fresh", "aging", "stale", "unknown"],
+          "description": "Freshness signal used to exclude stale context faster."
+        },
+        "evidence_kind": {
+          "type": "string",
+          "enum": ["file", "doc", "schema", "test", "command", "external", "signal", "diff", "unknown"],
+          "description": "Kind of evidence represented by this context entry."
+        },
+        "source_ref": {
+          "type": "string",
+          "description": "Optional source-local reference, such as issue id, frame id, URL label, or attachment name."
+        },
+        "sensitivity": {
+          "type": "string",
+          "enum": ["public", "internal", "sensitive", "secret"]
+        },
+        "verification_hint": {
+          "type": "string",
+          "description": "Follow-up check needed before treating this context as verified."
+        }
+      },
+      "additionalProperties": true
+    },
+    "efficiency_metrics": {
+      "type": "object",
+      "required": ["target_threshold_percent", "measurement_status", "scores"],
+      "properties": {
+        "target_threshold_percent": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "measurement_status": {
+          "type": "string",
+          "enum": ["estimated", "measured", "mixed"]
+        },
+        "scores": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/metric_score" }
+        },
+        "notes": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "metric_score": {
+      "type": "object",
+      "required": ["name", "score_percent", "basis", "confidence"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "score_percent": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "basis": {
+          "type": "string"
+        },
+        "confidence": {
+          "type": "string",
+          "enum": ["low", "medium", "high"]
+        },
+        "evidence_refs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "limit": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "external_context_profile": {
+      "type": "object",
+      "required": ["source", "source_ref", "kind", "included", "excluded", "reason", "confidence", "sensitivity"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "description": "External source name, such as Figma, GitHub, docs, attachment, dashboard, or another connector."
+        },
+        "source_ref": {
+          "type": "string",
+          "description": "Smallest useful source-local reference."
+        },
+        "kind": {
+          "type": "string",
+          "description": "External context kind, such as error_evidence, design_evidence, work_item, reference, runtime_evidence, or attachment."
+        },
+        "included": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "excluded": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "reason": { "type": "string" },
+        "confidence": {
+          "type": "string",
+          "enum": ["low", "medium", "high"]
+        },
+        "sensitivity": {
+          "type": "string",
+          "enum": ["public", "internal", "sensitive", "secret"]
+        },
+        "verification_hint": { "type": "string" },
+        "blocked_reason": { "type": "string" },
+        "next_action": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/templates/tink/schemas/context-metrics-evaluation.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dotoricode/tink-harness/schemas/context-metrics-evaluation.schema.json",
+  "title": "Tink current run context metrics evaluation",
+  "type": "object",
+  "required": ["run", "evaluator", "target_threshold_percent", "measurement_status", "scope", "scores"],
+  "properties": {
+    "run": {
+      "type": "string",
+      "description": "Run state path, usually .tink/current."
+    },
+    "evaluator": {
+      "type": "string",
+      "description": "Stable evaluator id, such as fixture-ratio-v1."
+    },
+    "target_threshold_percent": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100
+    },
+    "measurement_status": {
+      "type": "string",
+      "enum": ["estimated", "measured", "mixed"]
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["fixture", "current_run", "run_history", "production_telemetry"]
+    },
+    "limits": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "scores": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/metric_score" }
+    }
+  },
+  "$defs": {
+    "metric_score": {
+      "type": "object",
+      "required": [
+        "name",
+        "score_percent",
+        "formula",
+        "numerator",
+        "denominator",
+        "evidence_refs"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "enum": [
+            "unnecessary_context_reduction",
+            "initial_context_pack_size_reduction",
+            "review_evidence_lookup_time_reduction",
+            "verification_omission_detection",
+            "repeated_context_reuse_accuracy",
+            "rework_probability_reduction"
+          ]
+        },
+        "score_percent": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "formula": {
+          "type": "string"
+        },
+        "numerator": {
+          "type": "number",
+          "minimum": 0
+        },
+        "denominator": {
+          "type": "number",
+          "minimum": 0
+        },
+        "evidence_refs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "limit": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}