Skip to content

Make the verified capture path the one the commits skill teaches - #358

Merged
MongLong0214 merged 1 commit into
devfrom
fix-issue-340
Aug 1, 2026
Merged

Make the verified capture path the one the commits skill teaches#358
MongLong0214 merged 1 commit into
devfrom
fix-issue-340

Conversation

@MongLong0214

Copy link
Copy Markdown
Owner

Closes #340

skills/commitlore-commits/SKILL.md taught hand-written trailers first and
reached 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

  1. What a record is
  2. When to record
  3. The vocabulary (two tables)
  4. The harvest pipelineharvest --prompt-only, a worked draft JSON, a
    worked verified/rejected pair, --repair-prompt, then "fold the trailers in
    by 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_at at stage
time and refuses fabricated evidence, appeared nowhere.

After

  1. What a record is, and that capture is how it gets recorded
  2. When to record
  3. Capture — the five steps an agent executes: prepare → draft → verify →
    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 the
    five gates prepare-commit-msg applies at commit time plus the five-minute
    window that opens at stage — the part no prompt contract carries
  4. The vocabulary (one table)
  5. Fallback: writing the block by hand — stated to apply when capture cannot
    bind: a commit that already exists, or a repository without the hooks, with
    backfill named for past commits and harvest/harvest-verify for evidence
    checking 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

  • prepareverifystage round-tripped against the real stdio MCP server
    in a scratch repo, and separately through commitlore capture --transcript --draft; both reached a git commit whose trailer block the
    prepare-commit-msg hook appended on its own.
  • A fabricated quote was refused (evidence-not-found) with nothing staged, at
    exit 0.
  • Every command and tool name in the file was executed before being written down.
  • npx vitest run test/manifest.test.ts test/doctor.test.ts test/agent-configs.test.ts — 99 passed. (test/skills.test.ts does 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.

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
@github-actions

github-actions Bot commented Aug 1, 2026

Copy link
Copy Markdown

CommitLore — record lint

Trailers: clean — 1 commit in origin/dev..6947cf9612ad252479191bbf6d7720411fd1c3ba
Active constraints: 2 limits · 4 ruled-out · 1 warnings — from 2 records over 1 changed path

Active constraints for the paths this PR touches

Limits (2)

  • r-captureskill 6947cf9 — a skill loads into every agent's context, so a paragraph duplicating what the runtime prompt already prints is paid for on every session
  • r-9f3b16 6b13589 — git decides rename lineage by content similarity, so any claim about following renames is a claim about a threshold, not a guarantee

Ruled out (4)

  • r-captureskill 6947cf9 — 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
  • r-captureskill 6947cf9 — 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
  • r-9f3b16 6b13589 — assert only that renames are followed | it would pass with the threshold anywhere, which is the same as not testing it
  • r-9f3b16 6b13589 — paper over delete-then-recreate | git links nothing there, and pretending otherwise would invent a lineage

Warnings (1)

  • r-9f3b16 6b13589 (claim) — the 43/44 percent crossover is a property of git's -M default and this fixture generator, not a protocol guarantee -- if it moves, decide whether the new value is acceptable rather than editing the number to match

Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR.

@MongLong0214
MongLong0214 merged commit 4cc0d87 into dev Aug 1, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant