Skip to content
Back to search

repo-context-ledger

面向 AI 上下文管理的 Agent Skill:为 Codex 上下文管理、Cursor 上下文切换和 Claude 上下文管理提供跨窗口续接,用 Git 保存可验证的功能说明与变更记录。AI coding context management and agent handoffs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gviiisen/repo-context-ledger with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gviiisen/repo-context-ledger'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gviiisen--repo-context-ledger/badge.svg)](/listings/gviiisen--repo-context-ledger)

HTML

<a href="/listings/gviiisen--repo-context-ledger"><img src="/api/listings/gviiisen--repo-context-ledger/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone this repository or download a release, then install the directory `skills/repo-context-ledger` in your AI tool.

Codex

Ask Codex:

> Use `$skill-installer` to install the `skills/repo-context-ledger` skill from `https://github.com/gviiisen/repo-context-ledger`.

For repository-scoped use, copy or link the skill directory to:

.agents/skills/repo-context-ledger/

Claude Code

Copy or link `skills/repo-context-ledger` to either the personal or project skill directory:

~/.claude/skills/repo-context-ledger/
.claude/skills/repo-context-ledger/

Cursor

Import this GitHub repository from Cursor's Skills/Rules settings, or copy the skill to:

~/.agents/skills/repo-context-ledger/
.agents/skills/repo-context-ledger/

GitHub Copilot

Install the Skill through a compatible Agent Skills client, or let an initialized repository's `.github/copilot-instructions.md` route Copilot to the ledger. The runtime preserves existing Copilot prose outside its managed block.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 573 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Repo Context Ledger — Feature Change Ledger & Cross-Agent Context Relay
  2. [English](README.md) | [简体中文](README.zh-CN.md)
  3. [![skills.sh](https://skills.sh/b/gviiisen/repo-context-ledger)](https://skills.sh/gviiisen/repo-context-ledger)
  4. > Automatically record every behavior-changing feature update, then let Codex, Cursor, or Claude continue from the right code, decisions, and boundaries.
  5. Repo Context Ledger is an open, repository-level feature change ledger for AI coding. After a feature is added, fixed, or behaviorally adjusted, it preserves what changed, why it changed, where the implementation lives, which boundaries must remain stable, and how the result was verified.
  6. Those verified records become durable context for Codex, Claude, Cursor, GitHub Copilot, Grok, and other coding agents. A fresh window or a different tool can follow a focused route into the relevant code and continue without replaying a long chat or rediscovering the feature from scratch.
  7. Use it for AI feature change tracking, software change documentation, AI context management, Codex context management, Cursor context switching, Claude context management, and cross-agent development handoffs. The change ledger is the knowledge source; cross-session and cross-tool continuation are capabilities built on top of it.
  8. Install it with the standard Agent Skills CLI:
  9. ```bash
  10. npx skills@latest add gviiisen/repo-context-ledger --skill repo-context-ledger
  11. ```
  12. You make ordinary coding requests. The AI owns the documentation lifecycle.
  13. Before any lifecycle command, the Agent can ask the read-only Workflow Plan whether the request is understanding work, a small fix, an ordinary change, or a continuation. The plan reuses the bounded context router, explains its decision, and asks for clarification instead of guessing when intent is ambiguous.
  14. ## Why it exists
  15. AI-assisted changes are easy to implement but hard to preserve as durable repository knowledge. Without a feature-level record, the reason for a fix, its code path, verification evidence, and important boundaries remain trapped in a chat or must be rediscovered from a large diff and codebase.
  16. The same gap becomes more visible when work moves to a fresh window or another coding agent. The next agent must reconstruct the feature from scratch, and implementation details or important constraints can be lost between sessions.
  17. Repo Context Ledger records each behavior-changing feature addition, repair, and adjustment, then turns that verified history into a small, durable map of the repository:
  18. - where a feature lives;
  19. - how its code path works;
  20. - which contracts and edge cases must remain stable;
  21. - what changed, why it changed, and how it was verified;
  22. - which project and module README summaries need refreshing.
  23. ## What it maintains
  24. - `docs/ai/`: concise repository-wide orientation for fresh AI sessions.
  25. - `docs/ai/context-manifest.json`: generated feature-to-context routes for machine discovery.
  26. - `docs/ai/context-packs/`: minimal feature context, load order, boundaries, tests, and tracked-file fingerprints.
  27. - `docs/specs/`: current feature behavior, code maps, contracts, and boundaries.
  28. - `docs/changes/`: chronological implementation and repair handoffs, grouped as `YYYY/MM/<change>.md` with a small monthly index.
  29. - Private branch/worktree state: independent active and paused drafts are stored under Git metadata and are never committed; only completed changes enter formal history.
  30. - Root and module `README.md` files: generated navigation blocks without rewriting human prose.
  31. - `AGENTS.md`, `CLAUDE.md`, Cursor rules, and `.github/copilot-instructions.md`: thin native adapters that route coding agents to the same ledger.
  32. - `.context-ledger/writing-quality.md`: local evidence, language, and record-form rules available to every AI tool.
  33. ## Compatibility
  34. The core skill follows the open Agent Skills `SKILL.md` format. It is designed for Codex, Claude Code, Cursor, GitHub Copilot, Grok, and other agents that support Agent Skills or repository instruction files.
  35. Initialized repositories also receive plain instruction files, so tools without native Skill discovery can follow the same workflow. Native discovery and exact installation locations vary by product.
  36. See [COMPATIBILITY.md](COMPATIBILITY.md) for supported Python/platform and CLI schema guarantees, and [MIGRATIONS.md](MIGRATIONS.md) for upgrade rules.
  37. ## Install
  38. Clone this repository or download a release, then install the directory `skills/repo-context-ledger` in your AI tool.
  39. ### Codex
  40. Ask Codex:
  41. > Use `$skill-installer` to install the `skills/repo-context-ledger` skill from `https://github.com/gviiisen/repo-context-ledger`.
  42. For repository-scoped use, copy or link the skill directory to:
  43. ```text
  44. .agents/skills/repo-context-ledger/
  45. ```
  46. ### Claude Code
  47. Copy or link `skills/repo-context-ledger` to either the personal or project skill directory:
  48. ```text
  49. ~/.claude/skills/repo-context-ledger/
  50. .claude/skills/repo-context-ledger/
  51. ```
  52. ### Cursor
  53. Import this GitHub repository from Cursor's Skills/Rules settings, or copy the skill to:
  54. ```text
  55. ~/.agents/skills/repo-context-ledger/
  56. .agents/skills/repo-context-ledger/
  57. ```
  58. ### GitHub Copilot
  59. Install the Skill through a compatible Agent Skills client, or let an initialized repository's `.github/copilot-instructions.md` route Copilot to the ledger. The runtime preserves existing Copilot prose outside its managed block.
  60. ## Common usage examples
  61. After installation and one-time repository initialization, talk to your coding Agent normally. You do not need to run Ledger lifecycle commands yourself.
  62. | Situation | What you can say | What the Agent does |
  63. | --- | --- | --- |
  64. | Understand an existing feature | `Explain how withdrawal review works and where its boundaries are.` | Routes to the most relevant Pack and spec, then inspects the necessary code without creating a task session. |
  65. | Implement or fix behavior | `Fix duplicate withdrawal notifications.` | Creates a private task session, loads bounded context, expands through affected code and tests, verifies the result, and publishes one completed Change record. |
  66. | Continue in a fresh window | `Continue announcement API rate limiting.` | Finds your matching active or paused session, generates a Resume Capsule, and continues the same Ledger session rather than starting over. |
  67. | Switch AI tools | Open Cursor after Codex and say `Continue announcement API rate limiting.` | Uses the same vendor-neutral repository context and your principal-owned private session, while revalidating code and stale warnings. |
  68. | Temporarily switch tasks | `Pause this work, fix the login timeout, then let me return later.` | Checkpoints the current task and starts an independent private session, so their handoff drafts do not overwrite each other. |
  69. | Hand work to a teammate | `Transfer this paused task to principal p-…` or request a read-only/fork grant. | Creates an explicit expiring grant. Without one, another principal can use committed Packs, specs, and Changes but cannot read or mutate your private draft. |
  70. The routed files are a starting map, not a limit. The Agent must still read additional callers, implementations, configuration, persistence, permissions, concurrency, retries, tests, and external boundaries whenever they can affect the requested behavior.
  71. ## Tutorial
  72. ### 1. Initialize a repository once
  73. Open the target project with your AI coding tool and ask:
  74. > Use repo-context-ledger to initialize this repository.
  75. The agent first previews the exact operation list with `init --dry-run`, then applies the same plan with `init`. It creates the documentation structure, private workspace state, and durable agent instructions without overwriting existing documentation.
  76. For a manual preview, run:
  77. ```text
  78. python path/to/ledger.py --repo path/to/repository init --dry-run
  79. ```
  80. The output is a compact plan, not a full diff. It does not create a lock, repository file, or private session-state file.
  81. ### 2. Work normally
  82. Make the same request you would make without this skill:
  83. > Fix the withdrawal monitoring interface and verify the behavior.
  84. You do **not** need to run `ctx begin`, name a handoff, or remember lifecycle commands. The agent should autonomously:
  85. 1. produce a read-only `workflow-plan-v1` decision for the request;
  86. 2. retrieve the relevant repository and feature context when the selected workflow needs it;
  87. 3. start a private handoff only for a small fix or ordinary behavior change;
  88. 4. update code and execute claimed checks through the verification recorder;
  89. 5. derive changed paths from Git and record Before/After behavior, boundaries, and evidence;
  90. 6. update the stable feature spec and Context Pack when current facts or tracked dependencies change;
  91. 7. update affected module README prose when its usage changes, deferring shared generated summaries until merge;
  92. 8. close the handoff and validate structure plus Git-diff documentation coverage.
  93. On a feature branch, shared monthly indexes and README summary blocks are intentionally left unchanged until merge.
  94. ### Small fixes, less bookkeeping
  95. Similar follow-ups do not automatically restart the workflow. The Agent first checks what is actually new using context it already has: an ordinary log recheck needs no new Ledger task, and a same-window continuation keeps the active session. New behavior on another path still needs its own explanation and current verification. Reuse background and methods, not stale success claims; completed records remain unchanged.
  96. Ledger records acceptance goals, not every terminal operation. Reads, searches, file generation, and deployment preparation use ordinary tools. Reuse the current task session; run related acceptance checks through one reviewed script/preset instead of wrapping every helper separately. Preserve each step's result and failure exit code, keep required pre/post-deployment checks in their proper phases, and never replay a deployment merely to add logging. `--timings verify ...` separates subprocess time from Ledger overhead; it does not promise to shorten the tests themselves.
  97. One logical request produces one completed Change, including its code, tests, and documentation—not separate records for each file or step. Important findings, decisions, and useful failed approaches are kept in the same private draft as work progresses, not reconstructed only at the end. The small-fix form has nine authoring prompts: intent, Before, After, change explanations, invariants, failure/recovery, unchanged scope, documentation rationale, and open questions. The Agent still explains what changed and why; only the documentation file list is generated, and verification comes from executed checks.
  98. Coupled files can share an explanation and common boundaries without repeating a table for each file. A path list alone cannot pass the new short-form gate. There is no cap on meaningful change items: when the scope or risk grows, the Agent expands the same draft instead of dropping details. These checks catch missing references and fields, not every business mistake; the Agent must still reconcile the record with the actual diff. This is a shorter evidence-v1 form, not a bypass for risky one-line changes.
  99. For a known single-session fix, the Agent can go from `start --workflow small-fix` to implementation, `verify`, and `finish`, without a separate evidence command. Unrelated dirty work or parallel sessions still need explicit scoped evidence. Optional `finish --dry-run` reports closeout problems together without writing anything; it is not an extra required step. Pack `--reference` links provide optional reading guidance without adding fingerprint dependencies; existing tracked files are never silently downgraded.
  100. ### Optional global runtime
  101. `init --runtime global --dry-run` previews an opt-in installation where `.context-ledger/ledger.py` is only a portable forwarding entry to the globally installed Codex Skill. Project configuration and history remain local, while updating that global Skill updates the executable used by this entry. A missing global installation fails clearly rather than silently using an old version. Bundled standalone runtimes remain the default for portable checkouts and CI. See [global runtime migration](skills/repo-context-ledger/references/global-runtime.md) before changing a mature repository.
  102. ### Recording language and form
  103. The default quality policy is:
  104. ```json
  105. {
  106. "language": "auto",
  107. "detail": "standard",
  108. "max_context_pack_lines": 180
  109. }
  110. ```
  111. With `auto`, the agent follows nearby repository documentation, then the user's language when no convention exists. Paths, symbols, commands, protocol fields, and error text stay in their source form. Handoffs, stable specs, and Context Packs deliberately use different Markdown structures because they answer different questions; existing documents are not reformatted during upgrade.
  112. Initial context loading has its own production-safe budget:
  113. ```json
  114. {
  115. "context": {
  116. "max_required_files": 3,
  117. "max_linked_specs": 2,
  118. "max_change_summaries": 3,
  119. "max_total_characters": 30000,
  120. "show_close_candidates": 0
  121. }
  122. }
  123. ```
  124. Completed Change bodies are excluded from the initial read boundary. Increasing this budget should follow a measured repository need rather than compensate for oversized Packs.
  125. Coverage classification is configured separately in `.context-ledger/config.json`:
  126. ```json
  127. {
  128. "coverage": {
  129. "implementation_globs": ["**"],
  130. "test_globs": ["tests/**", "**/*.test.*", "**/*.spec.*"],
  131. "ci_globs": [".github/**", ".gitlab-ci.yml"],
  132. "config_globs": ["pyproject.toml", "package.json"],
  133. "generated_globs": ["dist/**", "build/**"],
  134. "ignore_globs": []
  135. }
  136. }
  137. ```
  138. The runtime applies ignored, generated, test, CI, and configuration rules before the implementation fallback. Projects can replace the defaults with repository-specific globs. A changed production path only passes Context Pack coverage when that exact path is tracked by a changed Pack; updating an unrelated Pack is not accepted.
  139. Project maintainers can also define reviewed verification presets in `.context-ledger/config.json`. The Agent selects a name; the runtime executes the stored argument array directly, so it does not need to improvise PowerShell quoting or rebuild a long command from prose:
  140. ```json
  141. {
  142. "verification": {
  143. "presets": {
  144. "unit": {
  145. "argv": ["python", "-m", "unittest", "discover", "-s", "tests", "-v"],
  146. "cwd": ".",
  147. "timeout": 300,
  148. "sensitive": false,
  149. "platforms": ["windows", "linux", "darwin"]
  150. },
  151. "windows-smoke": {
  152. "argv": ["powershell.exe", "-NoProfile", "-File", "scripts/smoke.ps1"],
  153. "platforms": ["windows"]
  154. }
  155. }
  156. }
  157. }
  158. ```
  159. Run one explicitly with `python .context-ledger/ledger.py verify --preset unit`. The first run, and the first run after a preset changes, stops and prints its exact digest; review the Git-tracked preset and repeat with `--trust-digest sha256:...`. Trust is per local principal and never enters Git. Presets never run during `init`, routing, or `finish`; they cannot carry environment variables or secrets. Shell strings such as PowerShell `-Command`, `cmd.exe`, and `bash -c` are rejected. See [verification-presets.md](skills/repo-context-ledger/references/verification-presets.md) for the complete contract.
  160. ### 3. Continue in another agent or switch tasks naturally
  161. When another agent or window will continue the same active task, the current agent records a checkpoint containing completed work, Git-derived changed paths, and the next concrete action. The task remains active; users do not run a checkpoint command themselves.
  162. Tell the agent what you want in ordinary language:
  163. > Pause the withdrawal monitoring fix and switch to the login timeout issue.
  164. For an actual task switch, the agent records a checkpoint, pauses that handoff, loads the login Context Pack, and starts the new work. Later, say:
  165. > Continue announcement rate limiting.
  166. The fresh window routes those keywords to one private task owned by the same principal, generates a bounded Resume Capsule, and continues the same Ledger session with a new epoch. It starts from the Pack, checkpoint, evidence paths, and verification, then reads any additional callers, implementations, configuration, storage, permissions, concurrency, retries, tests, or external boundaries needed for correctness. The Capsule saves aimless rediscovery; it does not authorize shallow code reading. Internal lifecycle commands remain agent-owned bookkeeping.
  167. Another principal cannot see or take over the private Capsule by default. Teammates continue from committed Packs, specs, completed Changes, and normal Git code; an unfinished task is shared only through an explicit expiring read-only, fork, or transfer grant. Private session state does not follow a fresh clone or another computer.
  168. ### 4. Collaborate with teammates
  169. Each person should work on a suitable Git branch or worktree. Codex, Cursor, Claude, Copilot, and Grok may share that person's principal, while another person has a different principal. Active and paused task state stays private; completed handoffs, stable specs, Context Packs, and code remain reviewable and mergeable through Git.
  170. Before opening or updating a pull request, the agent should update the base ref and run:
  171. ```text
  172. python .context-ledger/ledger.py team-check --base origin/main
  173. python .context-ledger/ledger.py check --strict --coverage --changed-since origin/main
  174. ```
  175. If another branch changed the same files or feature, coordinate and resolve that overlap before merging. After the pull request is merged, the agent runs this once on the configured default branch:
  176. ```text
  177. python .context-ledger/ledger.py sync --derived
  178. ```
  179. This rebuilds monthly indexes and managed README summaries from the merged source documents, avoiding routine generated-file conflicts between pull requests.
  180. These are still agent-owned lifecycle commands. The user can simply say, “check this branch before the PR” or “sync the ledger after the merge”; no command memorization is required. Teams can change `team.default_branch` or set `team.derived_updates` to `always` in `.context-ledger/config.json` when the default policy does not fit their workflow.
  181. ### 5. Start a new AI session
  182. Tell the new agent which feature or interface you want to change. Its native adapter points to the shared Context Manifest; the agent then loads the matching Context Pack and stable spec instead of scanning a large part of the repository. It never needs access to the previous product's private Memory.
  183. ### 6. Review the result
  184. After a completed change, expect to see:
  185. ```text
  186. docs/
  187. ├── ai/
  188. │ ├── context-manifest.json
  189. │ └── context-packs/
  190. │ └── withdrawal-monitoring.md
  191. ├── specs/
  192. └── changes/
  193. └── 2026/
  194. └── 08/
  195. ├── README.md
  196. └── 20260811123045-alice-a1b2c3d4e5-fix-withdrawal-monitoring.md
  197. ```
  198. The exact month is generated from the completion date. Monthly grouping keeps the history readable as the project grows.
  199. ## Safety and scope
  200. - Initialization is idempotent.
  201. - Existing documentation and README prose are preserved.
  202. - Existing `AGENTS.md`, `CLAUDE.md`, and GitHub Copilot prose outside managed blocks is preserved.
  203. - Only explicitly marked generated blocks are replaced.
  204. - Every configured path is validated to remain inside the repository before writes occur.
  205. - Handoff files use collision-safe creation and never overwrite existing history.
  206. - Git branches and worktrees keep independent active/paused task state; the old shared active pointer is migrated and removed.
  207. - Feature branches avoid shared derived files by default, and `team-check` reports likely team conflicts before review.
  208. - Active work cannot silently switch to another feature; it must be paused with resumable state first.
  209. - Context Packs detect missing or modified tracked files with SHA-256 fingerprints.
  210. - The Context Manifest is derived from packs, specs, and handoffs and is checked for drift on the default branch.
  211. - Optional Git-diff coverage catches behavior paths omitted from handoff evidence, stable specs, or Context Packs.
  212. - Private vendor Memory is never imported as authoritative repository knowledge.
  213. - Evidence-quality records reject unresolved language, placeholders, vague standalone claims, missing concrete paths, incomplete Before/After behavior, and unverified results.
  214. - Verification output is shown to the active agent; persisted evidence is limited to a hash, metadata and bounded redacted result/step summaries. Sensitive verification suppresses its command arguments and captured output.
  215. - Managed files use atomic replacement, and mutating commands use a short repository lock to prevent concurrent writers.
  216. - The runtime uses the Python 3.10+ standard library and requires no API key.
  217. - Semantic documentation remains the agent's responsibility; scripts enforce deterministic structure, lifecycle state, and links.
  218. ## Development
  219. Run the test suite:
  220. ```text
  221. python -m unittest discover -s tests -v
  222. ```
  223. Validate the Skill with the OpenAI Skill Creator validator:
  224. ```text
  225. python <skill-creator>/scripts/quick_validate.py skills/repo-context-ledger
  226. ```
  227. Runtime contributors edit `src/repo_context_ledger/runtime.py.tmpl` and build-time fragments, then run:
  228. ```text
  229. python scripts/build_runtime.py
  230. python scripts/build_runtime.py --check
  231. ```
  232. See [ARCHITECTURE.md](ARCHITECTURE.md) for the source/generated boundary.
  233. ## What's new in v1.0.3
  234. - The Agent judges what is actually new before invoking Ledger. Known-task follow-ups reuse their session and context; same-window "continue" no longer implies another lookup or resume. New behavior and uncertain boundaries still require investigation and evidence.
  235. - Small fixes use nine authoring prompts while preserving change explanations, documentation rationale, decisions and failed attempts. New short records reject path-only explanations, missing changed-path references, and empty inline fields; completed historical records are preserved.
  236. - Verification follows acceptance goals rather than every helper operation. An optional reviewed project-script example retains passed/failed/not-run steps; private timings distinguish subprocess work from Ledger preparation, recording and overhead. Required safety checks are not skipped or reordered.
  237. - `init --runtime global` optionally installs a small forwarding entry to the globally installed Codex Skill. Configuration, private sessions and history stay in the consuming repository; bundled standalone runtimes remain the default.
  238. - Optional `finish --dry-run` previews the actual finish gate without writing, and `pack --reference` separates optional reading links from tracked validity dependencies without silently downgrading existing dependencies.
  239. - Runtime Git reads disable optional index refreshes, so read-only previews also preserve `.git/index` when clean-file timestamps have changed.
  240. - The aggregate `policy --base` PR gate and hash-bound `audit --history --policy as-recorded` support immutable historical outcomes and documented later resolutions.
  241. Version note: v1.0.2 was developed in PR #27 but was not released separately. Its policy/audit work is included in v1.0.3, alongside the subsequent workflow improvements. No earlier release date or tag is being backfilled.
  242. ## What's new in v1.0.1
  243. - Automatic planning treats explicit typo, spelling, and comment-only work as `small-fix`. A one-line request is only supporting evidence when it also names a low-risk README, documentation, comment, copy, text, or example target; code risk remains `ordinary-change` even when the proposed edit is one line.
  244. - Workflow actions preserve an explicitly supplied `--tool`, so a planned `start`, `resume`, or context route keeps its Agent source in continuation records.
  245. - Rename-aware Git evidence and Coverage retain both the old and new path. Coverage requires the old implementation path to be owned by a Pack at the merge base, the new implementation path to be owned by a current Pack of the same feature, and the affected Packs to be refreshed. Moving production code into a test or generated directory cannot hide the removed boundary; copy sources remain informational.
  246. - New Git-tracked documents and configuration use mode `0644` on POSIX, while private sessions, state, cache, and preset trust use `0600`. Existing targets and copied runtime modes remain preserved.
  247. ## What's new in v1.0.0
  248. - The editable runtime is now split at tested boundaries for constants, errors, result models, repository locks, core Git access, and Workflow Planning. A deterministic builder still emits one zero-dependency `ledger.py`, so installation and `init` do not gain a package dependency.
  249. - Every public JSON protocol now has a checked-in Draft 2020-12 declaration under `schemas/`: `workflow-plan-v1`, `context-bundle-v1`, `resume-capsule-v2`, `doctor-v1`, `status-v1`, and `check-v1`.
  250. - Protocol tests execute real CLI commands and recursively compare successful, no-match, and error reports with the published schemas. The 1.x compatibility promise freezes required fields, meanings, and exit classes while leaving optional extensions open.
  251. - Extraction remains incremental: lifecycle, routing, health, and rendering stay in the template until a focused test boundary exists, avoiding a flag-day rewrite.
  252. ## What's new in v0.9.0
  253. - `plan --query` adds a read-only `workflow-plan-v1` front door with four explicit modes: `readonly`, `small-fix`, `ordinary-change`, and `resume`. It returns reasons, confidence, a confirmation flag, and a structured argument array for the next action without executing it.
  254. - Explicit intent is deterministic. Automatic planning uses bounded English and Chinese request signals plus principal-owned Resume Capsule discovery; an ambiguous request returns `clarify` instead of creating or resuming a session.
  255. - `context --format json` additively embeds the same Workflow Plan, while `start` rejects `readonly` and `resume` workflows so the decision layer cannot accidentally mutate task state.
  256. - A synthetic bilingual evaluation corpus and a golden contract fixture keep the planner behavior and machine schema reviewable without production prompts or repository data.
  257. - The primary `SKILL.md` was reduced from roughly 22,000 characters to under 12,000 and now routes detailed production, verification, and writing guidance through progressive-disclosure references.
  258. ## What's new in v0.8.2
  259. - Repository write locks carry a version, PID, start time, command, and random ownership nonce. The owner removes a lock only when both file identity and nonce still match, so it cannot delete a replacement lock created by another writer.
  260. - `doctor` distinguishes a live writer, stale process, unknown owner, malformed legacy metadata, and an unsafe symlink/non-regular lock path. Diagnosis is read-only and never removes a lock automatically.
  261. - Windows process liveness uses a read-only process query instead of signal emulation; Unix uses signal 0. Diagnostics expose only bounded lock metadata and no repository path.
  262. - Git-tracked verification presets require principal-local digest trust before their first execution and after every configuration change. A mismatch fails with `PRESET_TRUST_REQUIRED`; trust decisions stay below Git metadata and do not transfer to another user.
  263. - [SECURITY.md](SECURITY.md) and [THREAT_MODEL.md](THREAT_MODEL.md) document supported reporting, assets, trust boundaries, considered threats, recovery rules, and deliberate non-goals.
  264. ## What's new in v0.8.1
  265. - Git path collection now uses NUL-delimited byte output. Spaces, Unicode, quotes, literal backslashes, tabs, newlines, and rename destinations reach evidence and changed-scope checks without shell-style parsing or lossy unquoting.
  266. - Once a directory is confirmed as a Git worktree, required evidence, coverage, finish, and `check --changed-since` operations fail closed when Git cannot read repository state. Genuine non-Git directories keep the documented local fallback.
  267. - Machine-readable Git failures use the stable `GIT_COMMAND_FAILED` error code and bounded, redacted diagnostics instead of silently treating an unreadable index or ref as an empty change set.
  268. - Atomic runtime and managed-file replacement preserves an existing target's permission mode on Unix-like systems while retaining the same crash-safe replace behavior on every platform.
  269. - Focused repository-reliability tests cover complex Git filenames, Unicode renames, fail-closed corrupted-index behavior, and executable-bit preservation without storing production paths or data.
  270. ## What's new in v0.8.0
  271. - Resume Capsule v2 keeps the additive `context-bundle-v1` envelope while organizing private continuation guidance into goal, current state, next action, explicit code anchors, must-preserve contracts, verified facts, unresolved questions, Required reads, and cold-document exclusions.
  272. - Context Packs may declare bounded, human-maintained `Aliases` for phrases people actually use in different languages. `pack --alias` preserves those phrases across fingerprint refreshes; the runtime never invents translations or task state.
  273. - The router treats Pack code-map entries such as `file.go::Symbol` as first-class anchors. Exact aliases and symbols guide both Pack selection and an owned active/paused session without reading source bodies or foreign private drafts.
  274. - A fully synthetic continuation corpus evaluates owned-session Top-1 selection, multilingual aliases, path/symbol anchors, ambiguity blocking, foreign-overlap privacy, Capsule budgets, and required guidance without storing production names, paths, logs, or task content.
  275. - Automatic task-progress, diff, and symbol inference remains deliberately deferred. Capsule v2 restructures only explicit checkpoints, evidence, verification, Git position, and Git-tracked Pack/spec facts; Agents must still inspect every behavior-relevant code boundary.
  276. ## What's new in v0.7.3
  277. - Repository-owned verification presets replace improvised command strings with reviewed `argv`, working-directory, timeout, sensitivity, and platform metadata.
  278. - `verify --preset <name>` executes the selected argument array directly with `shell=False` and records the preset name plus repository-relative working directory as evidence.
  279. - Unsafe shell-string wrappers are rejected: PowerShell presets must use `-File`; `-Command`, encoded commands, `cmd.exe`, and shell `-c` forms cannot enter the configuration.
  280. - Presets are explicit only. Initialization, context routing, and finish never run them automatically, and presets cannot embed environment variables or secrets. Existing direct `verify -- <program> <args...>` usage remains compatible.
  281. ## What's new in v0.7.2
  282. - Small fixes with an already known code path use the short lifecycle: start, implement, run independent checks concurrently, and finish. They skip broad context routing and a separate evidence command unless the task becomes uncertain or another session requires explicit paths.
  283. - Independent `verify` processes execute concurrently and briefly wait for one another only while appending their private results. Checks that share a database, port, generated directory, or mutable fixture remain serial.
  284. - `finish` now prepares evidence and performs validation outside the repository write lock. A short final compare-and-swap step rechecks the session, private draft, specs, Packs, and publication target before atomic publication; derived indexes are regenerated afterward.
  285. - The optional global `--timings` flag prints private per-command stage timings to stderr. Timing data is not persisted and contains no repository paths.
  286. - A reproducible synthetic closeout benchmark compares the old serial choreography with the shorter overlapped workflow. In the recorded three-run fixture, median end-to-end time fell from 3.56 seconds to 2.31 seconds while the median finish lock hold stayed around 20 milliseconds; results vary by machine and checks.
  287. ## What's new in v0.7.1
  288. - Small tracked machine/worktree configuration changes now use a compact lifecycle: `start --kind local-config`, `verify --sensitive`, and `finish --path ...`.
  289. - Compact finish accepts only paths classified as configuration, captures task-scoped Git evidence, generates the semantic handoff, marks it `Scope: worktree-local`, and applies the stable-spec exception without manual Markdown editing or a separate `evidence` command.
  290. - Sensitive verification executes the real command but displays and persists neither its arguments nor captured output. The record retains only status, exit code, duration, and timestamp, and compact finish requires the final check to be sensitive and passing.
  291. - Generated Agent rules skip `context`/`focus` for this narrow path, require direct executable arguments instead of nested PowerShell quoting, and keep the full lifecycle for ordinary behavior changes.
  292. - `doctor` warns when unmanaged `.active-handoff` or legacy handoff-template instructions coexist with the private task-session workflow; it never deletes that prose automatically.
  293. ## What's new in v0.7.0
  294. - One deterministic build now generates both standalone runtime copies from `src/repo_context_ledger/runtime.py.tmpl` and ordered build-time fragments.
  295. - Version/schema/exit constants, `LedgerError`, and typed command-result contracts now live in ordered `constants.pyfrag`, `errors.pyfrag`, and `models.pyfrag` sources; further extraction can proceed gradually without changing the installed zero-dependency artifact.
  296. - `scripts/build_runtime.py --check` detects drift without writing, while ordinary builds use atomic replacement and normalized LF output. Two fresh builds are tested byte-for-byte and compiled as standalone Python.
  297. - Windows/Ubuntu CI checks generated-runtime drift before running the full suite. Runtime tests moved into a focused architecture test file rather than further enlarging the legacy monolithic test module.
  298. - Initialized repositories still receive one copied `.context-ledger/ledger.py`; users do not install a package and existing CLI/JSON contracts from v0.6.2 remain unchanged.
  299. ## What's new in v0.6.2
  300. - `status --format json` and `check --format json` add stable `status-v1` and `check-v1` automation contracts; existing text output and exit behavior remain available.
  301. - `context-bundle-v1` and `doctor-v1` stay unchanged. Golden fixtures protect schema names, required fields, the v8 repository configuration, the pre-v0.6.1 command set, and exit classes `0`, `1`, and `2`.
  302. - A versioned, fully synthetic routing corpus checks exact feature, title, and tracked-path selection without importing production repository data.
  303. - Windows and Ubuntu CI now run on both the minimum supported Python 3.10 and Python 3.12.
  304. - Compatibility and migration documents define additive minor-version rules, schema-breaking major-version rules, private-state boundaries, standalone-runtime upgrades, and rollback expectations.
  305. ## What's new in v0.6.1
  306. - `doctor` provides one bounded, read-only repository health report in human-readable text or the versioned `doctor-v1` JSON contract.
  307. - Health checks aggregate runtime/configuration, native adapters, the Context Manifest, private task state, Context Pack freshness and lifecycle, local documentation links, and feature-branch derived-file safety.
  308. - Stale and missing tracked paths are grouped by Pack and capped with `--max-items`, so mature repositories no longer receive hundreds of repetitive lines for one repair decision.
  309. - Duplicate current feature IDs and broken explicit lineage are errors. Shared tracked files are warnings only; the runtime never auto-supersedes a Pack from file overlap.
  310. - Findings distinguish `pass`, `warning`, `repairable`, and `error`, include deterministic suggested actions, and never mutate files, sessions, fingerprints, Pack status, or lineage.
  311. ## What's new in v0.6.0
  312. - `context --query` now emits `context-bundle-v1`. It still returns one primary Pack and bounded Required reads, but also carries an optional PR baseline, route warnings, cache/index metrics, and a Pack-scoped Resume Capsule without loading source or Change bodies.
  313. - A disposable private cache below Git metadata reuses parsed Pack metadata and tracked-file digests. Pack edits, tracked-file stat or Git text-mode changes, missing/corrupt cache data, and tool-schema changes invalidate or rebuild safely; the cache never enters Git and never becomes an authority.
  314. - A reverse index shortlists expensive fingerprint checks while a cheap all-Pack metadata ranking remains as a correctness safety net. Exact owned-session features, titles, tracked paths, and PR-delta overlap cannot be excluded by the shortlist.
  315. - `context --baseline <ref>` resolves the merge base, boosts Packs that track the PR delta, and returns only bounded repository-relative relevant paths. An unresolved ref produces an explicit warning instead of a false baseline.
  316. - Resume Capsules rank recorded evidence against the selected Pack. Unrelated legacy paths are omitted by name and reported only as a count; the Agent must still inspect the current diff and every behavior-relevant code boundary.
  317. - The public [performance baseline](benchmarks/README.md) records only anonymous aggregates. In one 59-Pack observation, routing improved from about 10.55 seconds to 1.365 seconds cold and 0.913 seconds warm, while keeping the first Required reads at one file. The reproducible benchmark uses only synthetic Packs, code, and checkpoints.
  318. ## What's new in v0.5.10
  319. - A fresh Codex, Cursor, Claude, Copilot, or Grok window can use task keywords to route to one owned active/paused Ledger session. `context-plan-v2` creates a bounded Resume Capsule on demand from private state; it does not persist chat transcripts or a growing capsule Markdown file.
  320. - `resume --query "<keywords>" --tool <agent>` continues the same Ledger session instead of creating a replacement. It increments a continuation epoch, and subsequent lifecycle writes require `--epoch <n>` so a stale window cannot silently overwrite the newer checkpoint.
  321. - Private sessions now have a pseudonymous principal owner independent of the Agent tool. Another principal receives only a foreign-overlap signal by default and cannot read the Capsule or resume, pause, checkpoint, verify, finish, or invalidate the task.
  322. - Explicit expiring grants support `read-only`, `fork`, and paused-session `transfer` workflows. A fork creates a new private child session and leaves the source untouched; a transfer changes ownership only when the recipient accepts it.
  323. - Required reads remain an initial route, never a cap on code investigation. Generated Agent policies require expansion through callers, implementations, configuration, persistence, permissions, concurrency, retries, tests, and external boundaries whenever they can affect the requested behavior.
  324. - Git-tracked Packs, specs, and completed changes remain shared normally. Private unfinished state stays in worktree Git metadata and still does not travel to another clone or machine.
  325. ## What's new in v0.5.9
  326. - `context --query` now emits a bounded `context-plan-v1`: exactly one primary Pack, only the linked specs that fit the configured file/character budget, and explicit Required reads.
  327. - `context --format json` provides a stable cross-Agent contract with repository-relative paths, selection confidence, budget usage, and local timing/file-count metrics.
  328. - Recent completed changes remain cold history. The plan may include bounded ID/title/feature/date/summary/evidence metadata from the Context Manifest, but it never loads a Change body into Required reads.
  329. - All generated Agent adapters prohibit recursive reads of `docs/ai`, `docs/specs`, and `docs/changes`; an Agent must read Required reads first, keep completed Change bodies cold, and name an unresolved question before expanding context.
  330. - `check --strict --changed-since <base-ref>` validates the merge-base delta plus directly related current Packs/specs, so unrelated pre-existing debt does not block the current PR while a source change that makes its Pack stale still fails. Coverage considers only private sessions whose evidence intersects the changed implementation paths.
  331. - Full `check --strict [--coverage]` behavior is unchanged and remains available for scheduled repository health audits and controlled release integration.
  332. ## What's new in v0.5.8
  333. - Context Pack fingerprints are portable across Windows and Unix checkouts: logically identical UTF-8 text receives the same digest with LF or CRLF line endings.
  334. - Git attributes remain authoritative. Files marked `-text`, files containing NUL bytes, and non-UTF-8 content remain byte-sensitive, so binary changes cannot be hidden by normalization.
  335. - Existing LF-based `sha256:` fingerprints remain compatible; a real text change still makes the related Pack stale.
  336. - Persisted verification commands, successful result lines, failure capsules, and not-run reasons replace repository, Codex, temporary, and user-home roots with `<REPO_ROOT>`, `<CODEX_HOME>`, `<TEMP_DIR>`, and `<USER_HOME>`.
  337. - Redaction recognizes ordinary Windows paths, slash-normalized paths, and JSON-escaped double-backslash paths. The currently visible historical records were corrected to remove five local absolute paths without rewriting Git history.
  338. ## What's new in v0.5.7
  339. - `init --dry-run` builds the exact same initialization plan as real `init`, then prints file creates, managed-block updates, deletions, migrations, detected modules, and a compact summary without writing repository files or private workspace state.
  340. - Preview and apply share one in-memory filesystem plan, so the preview cannot drift into a separate approximation of initialization behavior.
  341. - Dry-run does not acquire the repository write lock and remains read-only even while inspecting legacy workspace-state migrations.
  342. - Existing prose, mature change history, custom documentation paths, nested Git boundaries, and session drafts keep the same preservation rules during preview and apply.
  343. > Version note: v0.5.5 was reserved for this work but never released. The completed feature ships in v0.5.7; no published release or functionality is missing.
  344. ## Added in v0.5.6
  345. - `context --query` is a Context Pack router: it reads current Pack metadata, excludes superseded/archived Packs, penalizes stale fingerprints, and returns one primary Pack plus linked specs and the selection reason.
  346. - Omitting `--repo` walks up from the current directory to the nearest `.context-ledger/config.json` and stops at a nested Git repository boundary. An explicit `--repo` still wins.
  347. - Failed `verify` records a redacted Failure Capsule instead of only a hash. Success still stores a hash plus the last result line. Raw logs are not persisted.
  348. - Handoff Code paths may cite `file.go::Symbol`; the path part is matched against Git evidence.
  349. - Automatic single-session evidence skips generated/managed paths and refuses oversized dirty trees, so a shared worktree cannot silently swallow unrelated files.
  350. - The Skill now leads with the shortest path: read-only `context`/`focus`, small single-task `start → verify → finish`, and the full evidence/spec/Pack flow only for larger work.
  351. ## What's new in v0.5.4
  352. - Parallel-session evidence is explicit: when another task session exists, `evidence --session <id>` requires repeated `--path <path>` values and refuses to absorb the shared worktree's entire dirty set.
  353. - `finish` now uses a session-scoped gate. It validates only the selected draft, its recorded paths, explicit specs, and relevant Context Pack fingerprints.
  354. - Dirty paths and stale Context Packs belonging to another session no longer block the current session's publication; the current session's own stale Pack still fails closed.
  355. - Repository-wide `check --strict --coverage` remains the integration/PR gate instead of being an implicit per-session finish dependency.
  356. - Generated Agent rules explicitly forbid contacting another task because of foreign dirt, a stale Pack, or a failed global check.
  357. ## Added in v0.5.3
  358. - Active and paused handoffs are private session drafts under worktree Git metadata; `start`, `checkpoint`, `evidence`, and `verify` no longer add unfinished records to `docs/changes/`.
  359. - `finish` reserves a unique history path, validates the draft, atomically publishes one completed change, and deletes only that session's private draft after repository checks pass.
  360. - Interrupted publication is idempotent: a matching completed record can be validated and cleaned up on retry without duplicating history.
  361. - Registered v0.5.2 active or paused records migrate into private v7 drafts while completed and legacy history remains unchanged.
  362. - Ledger concurrency is explicitly limited to bookkeeping. It does not copy, lock, claim, merge, or coordinate source-code files; the host Agent and Git retain that responsibility.
  363. ## Added in v0.5.2
  364. - Task-scoped sessions replace the single active-handoff pointer: multiple coding tasks can keep independent active or paused handoffs in one worktree.
  365. - Every lifecycle command accepts `--session <id>`; when several sessions match, omission fails closed instead of selecting, pausing, or completing another task.
  366. - `verify` binds its target under a short lock, runs the external command without the repository write lock, then records the result under another short lock.
  367. - Generated Agent instructions prohibit unsolicited cross-task messages, delegation, steering, and interruption. Sharing a worktree does not grant coordination authority.
  368. - Existing v2-v5 active and paused state migrates into v6 task sessions without rewriting historical change records.
  369. ## Added in v0.5.1
  370. - Coverage path classes distinguish production implementation from tests, CI, configuration, generated output, managed ledger files, and project-specific ignored paths.
  371. - Repository-relative glob policies under `coverage` are validated, persisted by `init`, and remain optional for existing v5 repositories.
  372. - Context Pack coverage is now relational: every changed production path must be tracked by a Context Pack, and that related Pack must be refreshed.
  373. - Changing an unrelated Context Pack no longer satisfies `check --coverage`.
  374. - Coverage failures name the uncovered implementation path and the related Pack that was not updated.
  375. - Root translated READMEs and configured module READMEs are treated as managed documentation rather than production implementation.
  376. ## Added in v0.5.0
  377. - Native Context Bridge: `AGENTS.md`, `CLAUDE.md`, Cursor rules, and GitHub Copilot instructions route every supported agent to the same Git-tracked source of truth.
  378. - Context Manifest: `docs/ai/context-manifest.json` provides a deterministic machine-readable map from features to Context Packs, stable specs, tracked code paths, and recent changes.
  379. - Cross-agent checkpoints: an active task can record its verified state and next action without pausing, allowing another agent in the same worktree to continue it.
  380. - Adapter lifecycle: `adapters sync/check/status` preserves user prose while detecting missing or drifted native entry files.
  381. - Git-diff coverage gate: `check --coverage` reports behavior-changing paths that lack handoff evidence, a stable spec or explicit exception, or an updated Context Pack.
  382. - Private-memory boundary: Codex, Cursor, Claude, and Copilot Memory remain private caches; only code-verified facts are promoted to the shared ledger.
  383. - Schema v5 migration preserves existing records, custom documentation paths, mature history layouts, and README prose.
  384. ## Added in v0.4.1
  385. - Mature-repository adoption: existing `YYYY-MM/...` change trees are grouped at the month root instead of producing an index in every date or feature directory.
  386. - Existing monthly `YYYY-MM/index.md` files are preserved and reused as the month link; the runtime does not rewrite their human-maintained content.
  387. - Legacy and native trees for the same calendar month share one root-index entry, preferring an existing human-maintained month index.
  388. - Safe index cleanup: an obsolete `README.md` is removed only when the runtime can reproduce it byte-for-byte from current sibling records. Ambiguous or human-edited files are retained.
  389. - Worktree boundaries: module discovery stops at nested Git repositories and worktrees, preventing duplicate module entries and README updates.
  390. - Correct history counts: monthly `index.md` files are treated as indexes rather than change records.
  391. ## Added in v0.4.0
  392. - Evidence-first records: new handoffs, specs, and Context Packs use the backward-compatible `evidence-v1` quality profile.
  393. - Real verification capture: `verify` executes the check and records its command, status, exit code, duration, and output hash without persisting command output.
  394. - Git-derived evidence: `evidence` records actual changed paths so agents do not rely on memory.
  395. - Language policy: choose `auto`, `en`, or `zh-CN` while preserving source identifiers and commands.
  396. - Configurable detail: choose `concise`, `standard`, or `detailed`; Context Packs have a size limit.
  397. - Purpose-specific forms: handoffs capture Before/After evidence, specs capture current truth, and Context Packs remain minimal loading routes.
  398. - Legacy-safe adoption: existing records keep their language, format, filenames, and content until explicitly upgraded.
  399. ## License
  400. [MIT](LICENSE)
  401. <!-- repo-context-ledger:start -->
  402. ## Repository context
  403. - [Stable feature context](docs/specs/README.md)
  404. - [Change history](docs/changes/README.md)
  405. - [Feature Context Packs](docs/ai/context-packs)
  406. - Relevant specs: [Compact local configuration workflow](docs/specs/compact-local-config-workflow.md), [Context Routing Performance](docs/specs/context-routing-performance.md), [Continuation Quality](docs/specs/continuation-quality.md), [Contract Stability](docs/specs/contract-stability.md), [Coverage Integrity](docs/specs/coverage-integrity.md)
  407. - Latest recorded change: [Preserve Git index during read-only finish preview](docs/changes/2026/09/20260908000924-gviiisen-6acf617116-preserve-git-index-during-read-only-finish-previ.md)
  408. <!-- repo-context-ledger:end -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.