Document day-to-day PR workflow used throughout the project:
- What is a PR and why we use them
- Complete workflow from branch creation to merge
- Branch naming conventions (fix/, feat/, docs/, refactor/, test/)
- Commit message format with good/bad examples
- Review checklist and common patterns
- Merging strategy (squash vs regular)
- After merge cleanup steps
- Troubleshooting guide
- Real examples from recent PRs (eval-harness-phase1, smoke-to-test, sl-wiki-cross-links)
Captures the practical PR workflow we use daily in chat and makes
it accessible as reference documentation.
Sam & Claude
Replace jargon term 'golden tests' with clearer 'fixtures tests' throughout
the codebase. This aligns with the project's preference for explicit,
understandable terminology over obscure testing jargon.
Changes:
- Renamed crates/colibri-contracts/tests/golden.rs → fixtures.rs
- Updated comments in fixtures.rs and session.rs
- Updated docs: AGENTS.md, README.md, colibri.md, index.md
- Updated wiki: contracts.md, runtime-inventory.md, sl/contracts.md
Note: Kept intentional 'golden line' metaphor in COLIBRI-TOKENOMICS-TRIFECTA.md
as it refers to the concept, not the test file.
All gates pass:
- cargo fmt, clippy, test (14/14 in contracts)
- wiki-lint: 187/0
Covers the three root causes discovered during osa→debby SSH setup:
1. PasswordAuthentication no — removes fail2ban's reason to exist
2. AddKeysToAgent yes — prevents ksshaskpass popups on reconnect
3. FreeBSD PF rate limiting — defense in depth for osa
Sam & Hermes
New wiki page: model-selection-and-eval.md (445 lines)
Completes the T2.x trifecta design:
- Evaluation harness: 3 modes (self-report, local LLM, cloud LLM)
- Model selection: weighted scoring (success rate, cost, capability, latency)
- Integration with hive-routing: data flow + implementation phases
- 4 implementation phases, ~10 days total, ~570 lines
Indexed in both en/index.md and sl/index.md.
Follows PR #241 (conflict marker fix) and the now-merged screenshot
pipeline. The eval harness provides the feedback loop that makes
model-selection decisions data-driven rather than heuristic.
Sam & Claude
- colibri-mcp-ssh: subquery on hive_nodes to resolve
node_hostname to node_id for FK integrity
- wiki/mother-hive.md: new §Per-task cost aggregation
documents push vs pull, separate table rationale,
hostname-not-id decision
Sam & Hermes
1. contracts.md: add TaskCostSummary to active schemas table
2. MCP: rename colibri_get_task_cost → colibri_get_task
(returns full task with cost, not just cost fields)
3. heartbeat: try_lock() instead of lock().unwrap()
- WouldBlock → warn + defer to next tick
- Poisoned → into_inner() recover (SQLite WAL protects data)
Sam & Hermes
Full protocol surface audit across Colibri's 5 current protocols
(~5,324 lines). Key finding: A2A is an interoperability play, not a
complexity reduction play.
Replaced:
- Mother MCP-over-SSH bridge → A2A HTTP endpoint (−160 lines, +380 lines)
- External MCP discovery → Agent Card (future, zero adopters today)
- Ad-hoc cost format → typed A2A part (negligible code impact)
Not replaced: Unix socket (local IPC), spawner (process lifecycle),
glasspane (PTY observer), store (SQLite), MCP editor bridge (human↔tool).
Net delta: ~0 lines (moves code, doesn't shrink it). Protocol count: 5→6.
Recommendation: A2A is Phase 3 — not Phase 2, not 0.12. The current
MCP-over-SSH bridge (437 lines) works for 4 nodes. A2A pays off at 10+
nodes or when third-party tools ship A2A support. The Agent Card design
in HIVE-PANE.md stays as a north star.
Cross-linked from hive-pane.md + wiki index. 182 refs, clean lint.
Merges: HIVE-PANE.md (glasspane for hive), end-to-end cost capture test,
runtime-agnostic usage accumulation, test agent --emit-usage flag,
heartbeat() pub for tests.
Both wiki entries (hive-routing + hive-pane) preserved in index.
ProviderSmokeResult → ProviderTestResult
PROVIDER_SMOKE_SCHEMA → PROVIDER_TEST_SCHEMA
clawdie.provider-smoke.result.v1 → clawdie.provider-test.result.v1
(manifests, golden tests, wiki, zot_rpc comments)
Rationale: smoke is jargon; test is clear and consistent with
the project's naming conventions (avoid dead/fake/smoke labels).
GLASSPANE-TUI-DESIGN.md was a self-declared "scratch space" working doc
— but everything in it had shipped (the attention bar, n/N jump keys,
the `a` filter, the All-sessions fix). Its enduring decisions lived
only in this stale plan, while the wiki carried just a keybindings
table and a TODO roadmap stub.
Fold the durable design decisions into wiki/tui.md (the natural home —
it already had the keybindings section):
- complete the keybindings table (was missing n/N + a)
- "The attention model" section: needs_attention() definition, the
4h stall threshold rationale, attention-bar layout spec, row-highlight
color spec, and the session-filter-AND composition contract
Repoint the one code reference (the all_sessions regression comment in
main.rs) from GLASSPANE-TUI-DESIGN.md to the wiki section it now lives
in. Delete the 208-line scratch doc — zero remaining references.
wiki-lint --strict: 147 pass. TUI crate: fmt/clippy/20 tests green.
(Sam & Claude)
PR #146 made colibri's .agent/skills/ the canonical skills home (54
skills now live there; ISO imports from colibri). But the "clawdie-ai
is the source of truth" claim survived across FOUR layers, unchanged —
the canonical, linted, translated knowledge base described an
architecture that no longer exists.
Fixed across all layers:
- crates/colibri-skills: crate doc, field comments, Cargo.toml
description — all now name colibri/.agent/skills/ as the home.
- docs/wiki/skills-catalog.md (en): rewrote the "Source of truth"
decision + 6 scattered refs; repointed the 3 `docs/COLIBRI-SKILLS.md`
links to the crate code / store-schema.
- docs/wiki/sl/skills-catalog.md (sl): same correction; also fixed a
broken `import-clawdie-skills.sh` link (that script was deleted in
the clawdie-iso PR #146 followup).
- docs/wiki/index.md + sl/index.md: skills-catalog one-liners.
Deleted docs/COLIBRI-SKILLS.md (232 lines) — a stale roadmap that
duplicated the wiki, still called clawdie-ai the source of truth x3,
and referenced retired clawdie-ai paths. Repointed the layered-soul.md
(en+sl) references to skills-catalog.md / store-schema.md, and fixed
two stale `COLIBRI-SKILLS-PLAN.md` refs in import-layered-soul.sh.
wiki-lint --strict: 141 pass. colibri-skills: fmt/clippy/12 tests green.
(Sam & Claude)
Two fixes in one commit:
1. Terminology: ozadnji proces → proces v ozadju
- More natural Slovenian — noun inflects, prepositional phrase stays fixed
- 60 replacements across 19 sl/ files
- Glossary header updated to match
- Reverts the bad merge that restored "demon" in glasspane.md and
task-board.md (including enouporabniški→enonajemniški fix)
- Forms: proces v ozadju / procesa v ozadju / procesu v ozadju /
procesom v ozadju / procesov v ozadju
2. New wiki page: daemon-not-demon (EN + SL)
- Explains the FreeBSD daemon (Beastie mascot, helper spirit) vs
Slovenian demon (devil, bad spirit)
- Documents the decision to use proces v ozadju in Slovenian
- Confirms daemon (with a) is the only English spelling in Colibri
- Linked from both EN and SL wiki indexes
Standardize Slovenian wiki terminology after 9ca7ac6 and dc752d6:
- krajevni → lokalni (glasspane, headroom-sidecar, task-board)
- oprema → vprega (glasspane, naming-decisions — harness context)
- vrata za poslušanje → vhodna vrata (glasspane)
- Vrata za branje/pisanje → Preverjanje za branje/pisanje (external-mcp)
- demon → proces (task-board — single-tenant context)
- enonajemniški → enouporabniški (task-board)
Skips (correct idiomatic Slovenian):
- vhodna vrata (agent-harness — front door, not quality gate)
- vmesna programska oprema (cost-model — middleware)
- demon (standalone — standard term for daemon process)
Sam & Hermes
Glossary alignment — demon (devil) replaced with the established ozadnji
proces (background process) per okrajsave.md glossary. Full sweep across
all sl/ wiki and guide files (61 replacements in 18 files).
demon→ozadnji proces (nominative, 15 instances)
demona→ozadnjega procesa (genitive, 42 instances)
demonom→ozadnjim procesom (instrumental, 1 instance)
demonov→ozadnjih procesov, demonovem/demonovim rephrased (3 instances)
krajevni→lokalni (7 instances across 4 files)
oprema→vprega (agent harness context, 3 instances)
vrata→preverjanje (quality gate context, 1 instance)
The agent harness page describes THREE agents: pi (fallback), zot (default),
and Colibri (supervisor). Title updated in both EN and SL.
Also: H1 extraction fallback for pages without YAML frontmatter —
content.match(/^#\s+(.+)$/m)?.[1] so pages with only markdown H1 still
get a proper <title> tag instead of the slug.
agent-harness.md listed only zot's end-to-end proof (zot_rpc_smoke.rs,
ignored, ZOT_BIN-gated). pi now has better default CI coverage via
pi_spawn_live.rs (unignored, runs every test run), plus the new
default_agent_args unit tests proving the autospawn argv contract.
Also moves the autospawn argv reference into its own bullet for clarity.
