Make the verified capture path the one the commits skill teaches - #358
Merged
Conversation
The commits skill opened on hand-written trailers and reached the capture pipeline only as an aside, so an agent following it end to end produced a record that nothing had checked. Capture is the surface that binds a record to a nonce, hashes the transcript and staged diff it was drafted from, and refuses a quote that does not appear in those bytes; harvest checks the quotes but binds nothing to a HEAD, a diff or an expiry; a trailer block typed from memory is checked for shape alone. The skill defaulted to the weakest of the three. Capture is the body of the file now, in the five steps an agent actually executes -- prepare, draft, verify, stage, commit -- with the MCP tool names and argument shapes alongside the CLI equivalents, and with the part no prompt contract carries: the five gates prepare-commit-msg applies at commit time, and the five-minute window that opens at stage. Every command and tool name in it was run against a scratch repository before it was written down. Hand-writing moved to a fallback that states when it applies -- a commit that already exists, or a repository without the hooks -- and points at backfill for past commits, which reconstructs through the same verified loop instead of from memory. The harvest walkthrough went with it, and the drafted-JSON example with that: prepare's prompt prints both at the moment they are needed, so a second copy here was paid for by every session that loads this file, in order to teach the older path first. Record-Id: r-captureskill Limit: a skill loads into every agent's context, so a paragraph duplicating what the runtime prompt already prints is paid for on every session Ruled-out: Documenting both paths as equals | an agent takes the first workable path it reads, and the manual one produces a record no checker has seen Ruled-out: Dropping the vocabulary table along with the harvest walkthrough | it is what the fallback writes from and what a reader parses existing records with, and neither of those has a prompt contract to lean on Certainty: firm Blast: local Undo: easy Verified: prepare/verify/stage round-tripped over the real stdio MCP server and through commitlore capture --draft in a scratch repo, both reaching a commit whose trailer block the hook appended; a fabricated quote was refused as evidence-not-found at exit 0; manifest, doctor and agent-configs suites pass at 99; the file is 151 lines against 162 Unverified: whether an agent reading only this file installs the hooks it names -- the file points at commitlore-setup rather than restating init
CommitLore — record lintTrailers: clean — 1 commit in Active constraints for the paths this PR touchesLimits (2)
Ruled out (4)
Warnings (1)
Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #340
skills/commitlore-commits/SKILL.mdtaught hand-written trailers first andreached the capture pipeline only as an aside, so the product's own agent
workflow defaulted to the one path with no verification behind it.
Before
harvest --prompt-only, a worked draft JSON, aworked verified/rejected pair,
--repair-prompt, then "fold the trailers inby hand and commit"
Trailer syntax was the thing the reader was being taught to produce.
capture,the transaction that binds a record to a nonce, anchors
expires_atat stagetime and refuses fabricated evidence, appeared nowhere.
After
stage → commit, with the MCP tool names and argument shapes
(
commitlore_prepare_capture,commitlore_verify_capture,commitlore_stage_capture) alongside the CLI (commitlore capture --transcript … --draft …), the rejection reasons verify returns, and thefive gates
prepare-commit-msgapplies at commit time plus the five-minutewindow that opens at stage — the part no prompt contract carries
bind: a commit that already exists, or a repository without the hooks, with
backfillnamed for past commits andharvest/harvest-verifyfor evidencechecking without the transaction
Net 151 lines against 162. The harvest walkthrough and the drafted-JSON example
came out because
prepare's prompt prints both at the moment they are needed;the vocabulary table stayed because the fallback writes from it.
Verified
prepare→verify→stageround-tripped against the real stdio MCP serverin a scratch repo, and separately through
commitlore capture --transcript --draft; both reached agit commitwhose trailer block theprepare-commit-msghook appended on its own.evidence-not-found) with nothing staged, atexit 0.
npx vitest run test/manifest.test.ts test/doctor.test.ts test/agent-configs.test.ts— 99 passed. (test/skills.test.tsdoes not exist;those are the files matching skill/plugin/manifest, and no test asserted the
old harvest-first content.)
Known gap, not closed here
The transcript is composed by the same agent that writes the draft, so
"refuses fabricated evidence" means "refuses quotes absent from what the agent
submitted as the transcript". The skill now says to write it in the words
actually exchanged rather than a summary, but nothing mechanical enforces
transcript fidelity.