Packet — .agents/skills/colibri-verification/SKILL.md body rewrite

1. Plan

Section-by-section surgical edits using the Edit tool. Most of the body is preserved (the R82.K rewrite is sound); this round augments four specific sections with live-code citations and the session_id honesty caveat, and refreshes the trailing italic stamp.

2. Edit list (in execution order)

Edit 1 — Top-of-file reality stamp refresh

  • Anchor: line 9 (> **Phase 0 reality stamp (R76 — 2026-04-18)** ... line).
  • Change: Append a second sentence to the existing reality stamp paragraph: a short note that the body was reconciled this round to add live-code citations and to acknowledge the session_id gap. R76.H2 wording stays — that stamp is the historical anchor.
  • Net delta: ~1 sentence added.

Edit 2 — Pre-Execution / Audit Session — writeback hard-block context

  • Anchor: §4 of “Pre-Execution Readiness Checklist” — “Audit Session” subsection (lines 65-69).
  • Change: Add a final bullet noting that the audit-session ID is the key the post-execution writeback hard-block (src/domains/tasks/writeback.ts:97) checks indirectly via task_id — i.e. record the session early so the writeback bind isn’t an afterthought.
  • Wording principle: this is a forward pointer, not a duplication of the writeback section.
  • Net delta: ~1 bullet added.

Edit 3 — Post-Execution / Colibri Writeback — hard-block citation

  • Anchor: §1 of “Post-Execution Completion Checklist” — “Colibri Writeback (REQUIRED)” subsection (lines 110-113).
  • Change: Add a one-line note immediately after the existing checklist items explaining that this step is runtime-enforced: enforceWriteback(db, taskId) at src/domains/tasks/writeback.ts:97 blocks the status="done" SQL UPDATE if no thought_record exists for the task. Reference CLAUDE.md §7. Mention the call site at src/domains/tasks/repository.ts:475.
  • Wording principle: explicit “runtime-enforced, not convention” framing matches CLAUDE.md §7.
  • Net delta: ~3 lines added.

Edit 4 — VERIFY Acceptance Criteria — verifier citation

  • Anchor: §VERIFY Acceptance Criteria table row “Audit chain intact” (line 206).
  • Change: Update the table row’s “Tool” column from bare audit_verify_chain to audit_verify_chain plus a footnote/inline reference to the implementation verifyChain at src/domains/trail/verifier.ts:119.
  • Wording principle: keep the table compact; add the line citation as an inline parenthetical, not a new column.
  • Net delta: ~0 lines (one row text expanded inline).

Edit 5 — Verification Tools Quick Reference — Phase 0 honesty

  • Anchor: code block lines 230-259.
  • Change:
    • Add a leading paragraph (above the code block) explaining the canonical proof-grade ordering AND the Phase 0 reality: merkle_finalize(session_id=X) queries thought_records WHERE session_id = ? (src/tools/merkle.ts:296-300) but the thought_record MCP tool input schema (src/domains/trail/repository.ts:114-119) does NOT accept session_id. So in current Phase 0 the proof-grade chain is incomplete — merkle_finalize will throw NoThoughtRecordsError. ADR-007 (Proposed) addresses this by adding session_id to the thought_record input schema and writing it through to the DB column added in migration 006_eta.sql:54.
    • Update the code block: drop session_id from the thought_record call (matching the shipped Zod input schema), and add a // TODO: ADR-007 … comment marking the gap. The audit_verify_chain and merkle_finalize calls keep session_id because they DO accept it.
  • Wording principle: do not pretend the gap is closed; do not duplicate ADR-007 content; just signal the gap and point readers to it.
  • Net delta: ~10 lines added (paragraph + comments).

Edit 6 — Common Verification Failures — new row

  • Anchor: failure-mode table at lines 266-272.
  • Change: Add one row covering the merkle_finalize zero-records failure that occurs when thought_record was called without session_id (which is the only mode currently shipping). Failure column: merkle_finalize raises NoThoughtRecordsError. Cause column: shipped thought_record does not yet accept session_id (gap; ADR-007 Proposed). Resolution column: until ADR-007 lands, scope merkle_finalize to sessions whose thought_records were written via a backfill UPDATE; for new code, wait for ADR-007.
  • Net delta: 1 table row added.

Edit 7 — See Also — additional cross-references

  • Anchor: “See Also” list (lines 290-293).
  • Change: Add two bullets:
    • docs/agents/writeback-protocol.md — canonical writeback protocol contract
    • docs/architecture/decisions/ADR-007-... (Proposed) — closes the session_id gap
  • Net delta: 2 bullets added.

Edit 8 — Trailing italic stamp refresh

  • Anchor: line 297 (italic update note).
  • Change: Append a new italic sentence stating: rewrite hygiene round (post-R83), 2026-05-05 — body augmented with live-code citations to writeback hard-block (writeback.ts:97) and chain verifier (verifier.ts:119), verifyCompletion example reconciled to Phase 0 thought_record schema with ADR-007 (Proposed) gap acknowledgement, new failure-mode row added. Frontmatter byte-stable. Mirror at .claude/skills/colibri-verification/SKILL.md flagged for resync (separate task).
  • Net delta: 1 paragraph added.

3. What stays untouched

  • Frontmatter (lines 1-4).
  • HERITAGE note (lines 11-21) — already correct from R82.K.
  • Quick Reference table (lines 24-37).
  • Pre-Execution checklist sections 1-3 (Task Context / Task Validation / Environment Validation).
  • Execution Safety Checklist (entire).
  • Post-Execution Completion Checklist sections 2 / 3 / 4 (Thought Record / Merkle Proof / Git Checkpoint) — already cite the right tools and the ordering rule.
  • Phase Acceptance Criteria GATHER / ANALYZE / PLAN / EXECUTE / CLOSE rows.
  • Common Verification Failures existing rows.
  • Integration with Tier-1 Chains.

4. Risks & mitigations

Risk Mitigation
Adding line numbers (writeback.ts:97, verifier.ts:119) creates maintenance burden when those lines drift. Use the same lines CLAUDE.md §7 already names — co-drift means a single fix; net new fragility = zero.
Reconciling the JS example to drop session_id may cause copy-paste consumers to break their own scripts. Add explicit // TODO: ADR-007 inline comment so the consumer knows there’s a pending unification, and link to ADR-007 in the explanatory paragraph.
Adding the “Phase 0 honesty” caveat could read as “the proof-grade pipeline is broken”. Frame it as “Phase 0 ships with a known gap; the canonical ordering is sound and survives ADR-007 unchanged” — the gap is in the input schema, not the protocol.
npm test may have a snapshot test on this skill’s body. The skill content is not snapshotted in src/__tests__/. The capability index test (P0.6.3) only reads frontmatter — preserved. Build & lint are doc-agnostic.

5. Verification plan

After Edit 8:

  1. Read the rewritten file end-to-end — confirm flow.
  2. Run grep -E for the donor-tool pattern set, restricted to lines outside the HERITAGE note. Expect zero matches.
  3. Run grep for writeback.ts:97, verifier.ts:119, ADR-007. Expect each ≥ 1 match.
  4. Diff the frontmatter (lines 1-4) against origin/main’s file — expect zero diff.
  5. Diff the .claude/skills/colibri-verification/SKILL.md against origin/main — expect zero diff (mirror untouched).
  6. Run npm run build && npm run lint && npm test. Expect green.

6. Commit plan

Step Commit subject
1 (this packet) packet(rewrite-colibri-verification-skill): execution plan
4 (implement) feat(rewrite-colibri-verification-skill): rewrite SKILL.md body to 14-tool surface
5 (verify) verify(rewrite-colibri-verification-skill): test evidence

(Steps 1-3 already committed: audit, contract, packet.)

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.