tink-harness 1.2.2 → 1.3.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.3.0",
   "author": {
     "name": "dotori"
   }

package/CHANGELOG.md

@@ -7,6 +7,25 @@ All notable changes to Tink are tracked here.
 No unreleased changes yet.
 
 
+## [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.3.0 — context 효율을 점수화하고 선택한 context를 검증과 연결하는 Context Budget Ledger 기반.
 
 [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 효율 점수화를 위한 Context Budget Ledger는 `docs/context-budget-ledger.ko.md`와 `docs/context-budget-ledger.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.3.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.3.0 — Context Budget Ledger fields for scoring context efficiency and linking selected context to verification.</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 are documented in `docs/context-budget-ledger.md` and `docs/context-budget-ledger.ko.md` for scoring context efficiency 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.3.0`
 
 Tink follows semver from `1.0.0` onward.
 

package/commands/cast.md

@@ -188,6 +188,7 @@ 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.
 - `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.
@@ -227,6 +228,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 +260,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.

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

@@ -0,0 +1,56 @@
+# 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% 달성으로 표시하지 않는다.
+
+## 호환성 기준
+
+- 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,56 @@
+# 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.
+
+## 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/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/work-state.ko.md

@@ -39,6 +39,17 @@ 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`를 봅니다.
+
 `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

@@ -37,6 +37,17 @@ 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.
+
 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.3.0",
   "description": "Self-growing harnesses for Claude Code and Codex.",
   "license": "MIT",
   "type": "module",

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

@@ -188,6 +188,7 @@ 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.
 - `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.
@@ -227,6 +228,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 +260,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.

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

@@ -104,9 +104,11 @@ Create run state before deeper work:
 - `.tink/current/context-map.json`: machine-readable included/excluded context and reasons
 - `.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 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
+}