Design Spec
Architecture overview — entry format, retrieval strategy, quality lifecycle, and the federation vision.
The loop
Hortora is a closed loop between Claude sessions and a governed garden:
session
CAPTURE
MERGE
garden/
SEARCH
session
Entry format
Each entry is a markdown file with YAML frontmatter. The frontmatter carries structured fields for retrieval; the body carries the human-readable content.
id: GE-0042
title: Maven skips tests silently when Surefire version is missing
type: gotcha
technology: maven
tags: [testing, surefire, build]
status: active
---
## Symptom
`mvn test` completes with BUILD SUCCESS but no tests run...
## Root cause
...
## Fix
...
Three-tier retrieval
forage SEARCH finds entries in three passes, stopping when results are sufficient:
- By technology — scan entries matching the exact technology tag. Fast, targeted.
- By symptom — full-text match on symptom and title fields across all entries. Catches cross-technology patterns.
- Full scan — read all entry bodies. Used when the first two passes return nothing. Budget-limited to keep token cost bounded.
Quality lifecycle
Every entry has a status field that moves through a defined lifecycle:
- Active — current, verified, should be consulted
- Suspected — may be outdated or partially incorrect; flagged for review
- Superseded — replaced by a newer entry; kept for historical reference
- Retired — no longer applicable (e.g. for a deprecated library)
GitHub backend planned
The next phase replaces the local submissions queue with a GitHub PR workflow. Each submission becomes a pull request; CI runs validation and deduplication checks; merging the PR integrates the entry. GitHub Issues serve as stable entry IDs.
Federation planned
Gardens federate without centralisation. A canonical garden sets the standard for a domain. Child gardens enrich it with local context. Peer gardens share across domains. Each garden remains sovereign — federation is opt-in and additive.