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

1. Surface in scope

Exactly one file: .agents/skills/colibri-verification/SKILL.md.

2. MUST contain

After the rewrite, the body MUST contain:

  1. Frontmatter preserved. name: colibri-verification and the existing description string remain byte-stable. No new fields added.
  2. Top-of-file Phase 0 reality stamp that names the 14 shipped tools (preserve R76.H2 stamp + add this round’s stamp) and links to ADR-004.
  3. HERITAGE note explaining why donor families (roadmap_*, unified_*, gsd_*, context_*, memory_*, thought_plan/thought_decide, donor task-edges, audit_session_set_context/audit_session_end/merkle_attest, analysis_*/rag_*, server_info/server_shutdown) are NOT in Phase 0. Already correct from R82.K — do not regress.
  4. Three-phase verification checklist (pre-execution / execution / post-execution) — preserved from current body. The original purpose of this skill.
  5. Per-state acceptance criteria tables for the β state machine phases (GATHER → ANALYZE → PLAN → EXECUTE → VERIFY → CLOSE) — preserved from current body, with each table citing only 14-surface tools.
  6. Live-code citation: writeback hard-block — call out enforceWriteback at src/domains/tasks/writeback.ts:97 (and the call site at src/domains/tasks/repository.ts:475) as the runtime guard that turns the Post-Execution writeback step from convention into contract. Mirrors CLAUDE.md §7.
  7. Live-code citation: chain verifier — call out verifyChain at src/domains/trail/verifier.ts:119 as the implementation backing audit_verify_chain.
  8. Proof-grade workflow with honest Phase 0 caveat. Document the canonical audit_session_start → work → audit_verify_chain → final thought_recordmerkle_finalizemerkle_root ordering, AND explicitly note that the Phase 0 thought_record MCP tool (input schema at src/domains/trail/repository.ts:114-119) does NOT accept session_id, so merkle_finalize(session_id=X) will raise NoThoughtRecordsError until ADR-007 (Proposed) lands.
  9. Reference to ADR-007 (Proposed) as the path that closes the session_id gap. Phrasing: “Proposed”, not “shipped”.
  10. Updated verifyCompletion example. The JavaScript snippet should reflect Phase 0 reality (no session_id in the thought_record call) and carry an inline comment marking the gap.
  11. Common Verification Failures table row for the session_id/merkle_finalize zero-records failure mode.
  12. See Also link to docs/agents/writeback-protocol.md as the canonical writeback contract.
  13. Trailing italic update note describing this round’s reconcile.

3. MUST NOT contain

The body MUST NOT, after rewrite, contain any of these strings as invocable tool names (i.e. as code-literal MCP tool calls). Mentions inside the HERITAGE note framed as “NOT in Phase 0” are explicitly allowed — that is the note’s purpose:

  • roadmap_list, roadmap_get, roadmap_nodes, roadmap_register, roadmap_unregister, roadmap_progress_update, roadmap_progress_get, roadmap_progress_reset, roadmap_milestone_check, roadmap_validate, roadmap_repair, roadmap_node_get
  • unified_init, unified_set_project, unified_vitals, unified_backup, unified_metrics
  • gsd_* (every variant)
  • context_create, context_ensure, context_diff, context_verify
  • memory_pack, memory_bundle, memory_map, memory_verify, memory_gc, memory_smart_store, memory_tier_migrate, memory_cross_session, memory_semantic_search
  • thought_plan, thought_decide
  • task_eisenhower, task_deps, task_create_batch, task_link_roadmap, task_transition, task_delete, task_depends_on, task_report, task_sync_to_gsd
  • audit_session_set_context, audit_session_end, merkle_attest
  • analysis_rag_index, analysis_rag_search, rag_gc
  • ams_session_resume, server_info, server_shutdown

4. Tool surface — the 14 names that ARE permitted

The body’s tool references must be drawn only from this set (per ADR-004 R75 Wave H amendment):

Domain Tool
β Task Pipeline (5) task_create, task_get, task_update, task_list, task_next_actions
ζ Decision Trail (3) thought_record, thought_record_list, audit_verify_chain
η Proof Store (3) audit_session_start, merkle_finalize, merkle_root
ε Skill Registry (1) skill_list
System (2) server_ping, server_health

5. Shape constraints

  • File length: similar order of magnitude to current (~300 lines). Net delta target: +20 to +50 lines (additions). The R82.K body is already lean; this round adds citations, not bloat.
  • Headings preserved in their current order. New material lands inside existing sections (especially “Pre-Execution / Audit Session”, “Post-Execution / Colibri Writeback”, “VERIFY Acceptance Criteria”) and as one new sub-block before “Common Verification Failures”.
  • Markdown only. No HTML, no embeds.
  • Internal links: relative paths from .agents/skills/colibri-verification/ (i.e. ../../../docs/...).

6. Outputs

  • The rewritten .agents/skills/colibri-verification/SKILL.md.
  • 5-step chain artifacts: this contract, the audit (already committed), the packet (next step), and the verification doc (after implement).

7. Non-outputs

  • .claude/skills/colibri-verification/SKILL.md — NOT modified.
  • ADR-007 — NOT authored.
  • Other skills — NOT modified.
  • Source code — NOT modified.

8. Acceptance — gates

The implementation step is complete when:

  1. grep -E '\b(roadmap_|unified_|gsd_|context_|memory_|thought_plan|thought_decide|task_eisenhower|task_deps|task_create_batch|task_link_roadmap|audit_session_set_context|unified_backup|merkle_attest|audit_session_end|task_transition|server_shutdown|rag_)' .agents/skills/colibri-verification/SKILL.md matches only lines inside the HERITAGE note (i.e. lines that explicitly frame the donor name as “NOT in Phase 0”).
  2. The body cites src/domains/tasks/writeback.ts:97 exactly once (or twice — body + a “See Also” cross-link is fine).
  3. The body cites src/domains/trail/verifier.ts:119 exactly once.
  4. The body references “ADR-007” with the qualifier “Proposed”.
  5. The frontmatter is byte-stable (diff against the head of the file restricted to lines 1-4 shows zero changes).
  6. npm run build && npm run lint && npm test is green at HEAD of the feature branch.

Back to top

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

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