Skip to main content

hornero 🪶

Repo-native product loop: requirement signals → living memory → SDD specs → dispatched builds → HTML reports. Everything lives in your git repo; nothing needs a server, a database service, or a SaaS.

El hornero (ovenbird) builds its own house, layer by layer — so does this tool: hornero is developed with the same spec-driven workflow it implements (fully self-hosting).

What it does

 meeting notes, docs, ideas          you                     coding agents
        │                             │                            │
        ▼                             ▼                            ▼
 .hornero/inbox/  ──reconcile──▶  HITL review  ──apply──▶  sdd/specs/*.md
        │            (LLM drafts      approve/reject           │
        │             deltas with     /edit/skip               ▼
        │             VERBATIM        in your TTY         hornero build
        │             evidence)                          (spec → brief →
        │                                                 mock/cli backend)
        ▼                                                      │
 .hornero/knowledge/  ◀──reindex──  write-back: code + spec + reports
                                    land in the SAME branch/PR
        ▼
 sdd/reports/*.html   (capabilities, workflows, traceability — offline, deterministic)
  • Signals in: drop meeting notes / docs into .hornero/inbox/.
  • Project factory: create a Git repository and runnable stack from a composable, versioned blueprint; lock hashes expose local drift.
  • Reconcile: an LLM drafts RequirementDeltas (NEW / CHANGED / OBSOLETE / DUPLICATE) — every delta carries evidence that is a mechanically verified substring of the source signal. No evidence, no delta.
  • Human gate: nothing mutates a spec without an interactive approval (approve / reject / edit / skip). No TTY → no writes, by design.
  • Specs are the tracker: markdown files with YAML frontmatter under sdd/specs/; status transitions and comments are written into the files themselves. ADRs in sdd/decisions/, low-confidence ideas become brainstorm proposals in sdd/proposals/.
  • Build: approved specs are rendered into build briefs and dispatched to a coding-agent backend (mock by default; cli/api are explicit opt-ins).
  • Reports: capabilities.html, workflows.html, traceability.html — the full audit chain signal → delta → spec → SDD tasks → PR → merge, with honest gaps.
  • SDD toolkit sync: hornero sdd install|status|diff|sync manages your .claude/ + sdd/ toolkit files against an upstream repo with a committed lockfile and a three-way drift model — like a package manager for prompts, where diverged files are never auto-merged.
  • Agent-facing wiki: wiki/ is a second projection of the knowledge layer, written FOR the next agent run — watermark-scoped surgical updates, anti-stub and link-check gates, and a no-op discipline that makes scheduled refreshes churn-free (quiet days produce no PR).
  • Code as signal: opt-in GitSource turns commits into requirement signals so specs and code never silently drift apart.
  • Flight recorder & scribe: every dispatch leaves a redacted action-stream trace; the scribe distills it into a Decision Record whose every claim cites a verified event range — and past rejections resurface in the HITL preview before you approve a repeat.
  • Semantic project graph: sources, requirements, criteria, controls, tasks, code, tests, decisions and findings are connected with source hashes and evidence locators. validate repairs derived state and fails closed on corrupt traceability.
  • Continuous improvement: deterministic architecture, security, compliance, dependency, performance, quality, test, documentation and graph packs produce stable findings. Approved low-risk work runs in an isolated Git worktree; gates must pass before a review branch is retained.
  • Temporal intelligence: immutable entity versions, supersession, contradiction/duplicate candidates, impact paths, coverage scores, explainable queries and token-budgeted context packs.
  • Production factory: signed blueprint registries, three-way upgrades, capability resolution, production components, generated contracts and federated multi-repository plans.
  • Assurance: expiring finding baselines, declarative policy packs, offline SBOM/vulnerability input, STRIDE threat models and evidence mappings for SOC 2, ISO 27001, GDPR and PCI.
  • Autonomous runtime: signed webhook/schedule events, resource sandbox, budgets, retries, risk approvals, provider-neutral PR creation, metrics and bounded feedback learning. It never merges a branch.

Install

Requires Python ≥ 3.11. Single runtime dependency (pyyaml).

git clone <this-repo> && cd hornero
python -m venv .venv && source .venv/bin/activate
uv pip install -e .            # or: pip install -e .

Quickstart

hornero new billing-api --blueprint python-service --commit
cd billing-api
hornero ingest product-requirements.docx
hornero reindex
hornero validate
hornero improve scan
hornero improve plan --limit 20

For an existing repository:

cd your-project/
hornero init                   # scaffolds .hornero/ + the sdd/ layout
echo "Users keep asking for CSV export of the usage table" \
  > .hornero/inbox/note-2026-07-08.md
hornero reconcile --dry-run    # see the proposed deltas, writes nothing
hornero reconcile              # review interactively, apply approved deltas
hornero build                  # dispatch approved specs (mock backend)
hornero reindex                # rebuild local knowledge graph + HTML graph report
hornero report                 # regenerate sdd/reports/*.html
hornero status                 # spec counts, inbox, index health

Add the shared SDD toolkit (agents, commands, rules, templates):

hornero sdd install --from <toolkit-repo-or-path>
hornero sdd status             # drift table: current/behind/modified/diverged/...
hornero sdd sync               # fast-forward what's safe; diverged blocks

CLI at a glance

Command Purpose
hornero new NAME [--blueprint NAME] [--component NAME] Create a Git repository and full Hornero/SDD stack from a versioned blueprint
hornero init [--hooks] [--no-sdd] Scaffold .hornero/ + sdd/ layout (+ optional post-merge reindex hook)
hornero blueprint list|status List built-ins or report locked blueprint version and file drift
hornero ingest FILE... [--kind KIND] Normalize supported documents into the inbox with provenance
hornero validate [--repair] [--json] Validate graph schema, provenance, traceability and secret safety
hornero improve scan|plan|run|status Detect, prioritize, policy-gate, isolate, verify and ledger improvements
hornero knowledge history|analyze|impact|coverage|semantic-query|explain|context Navigate temporal reasoning, impact and bounded agent context
hornero extract FILE Propose graph entities from AI output with verbatim evidence gates
hornero blueprint resolve|upgrade Resolve capabilities or apply a signed three-way blueprint upgrade
hornero contracts generate|check Generate OpenAPI, event/data schemas and client contracts
hornero workspace graph|plan Federate repository graphs and calculate cross-repo impact
hornero assurance supply-chain|threat-model|compliance Generate auditable security and compliance evidence reports
hornero runtime init|emit|webhook|tick|approve|feedback|status Operate the bounded event runtime
hornero status Spec counts by state, pending inbox, index health
hornero reconcile [--dry-run] Poll signals → evidence-verified deltas → HITL → apply
hornero build [SPEC-ID ...] [--backend mock|cli] Approved specs → briefs → dispatch
hornero reindex Rebuild .hornero/knowledge/: token index + code graph DB + knowledge-graph.html
hornero knowledge query|page|related|entity|relations|status Query file and semantic graph surfaces
hornero report [--only NAME] Regenerate the HTML reports
hornero sdd install --from SRC [--ref R] [--force] Install toolkit + scaffold + lockfile
hornero sdd status / diff [FILE] Drift table / unified diff vs upstream
hornero sdd sync [--dry-run] [--theirs F] [--ours F] [--force] Pull updates; diverged requires explicit resolution
hornero sdd sync --push FILE... Promote improved files upstream via a PR (secret-scanned)
hornero sdd sync --workspace DIR Pull-sync every child repo carrying .hornero/sdd.lock
hornero sdd hold|unhold|pin FILE Per-file sync policy
hornero wiki init|update Agent-facing living wiki (watermark-scoped, no-op-disciplined)
hornero runs list|show|adopt|prune Flight-recorder traces of every dispatch
hornero scribe RUN [--force] Distill a trace into a Decision Record (verified citations)

Hard invariants

  1. Evidence is verbatim or the delta dies — excerpts are mechanically verified substrings of the signal; mismatches are dropped and ledger-logged.
  2. HITL is fail-closed — no approval channel ⇒ no spec mutation, no dispatch. --dry-run always leaves git status clean.
  3. No billed backend by surprise — api never runs unless it is the explicit first entry of dispatch.backend_order.
  4. Diverged toolkit files are never auto-merged — no timestamp heuristics; a human resolves with --theirs / --ours or by hand.
  5. Deterministic tests only — the suite needs no network, keys, or services.

Documentation

Specs are the source of truth: see sdd/specs/.

License

MIT

Metadata

Release files for hornero 0.4.0.post1001

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hornero 0.4.0.post1001
File Size Uploaded Provenance Actions
hornero-0.4.0.post1001.tar.gz 454.1 kB With provenance Details for hornero-0.4.0.post1001.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hornero 0.4.0.post1001
File Interpreter ABI Platform Actions
hornero-0.4.0.post1001-py3-none-any.whl Python 3 none any Details for hornero-0.4.0.post1001-py3-none-any.whl

Total release size: 612.1 kB

Release files / hornero-0.4.0.post1001.tar.gz

Download URL hornero-0.4.0.post1001.tar.gz
Size 454.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c50a0540555fa1858411b45d92f4ff9053b3192499facb302182a6f8388d66c4
BLAKE2b-256 checksum
How to use checksums
685a3a1e8444d5b804fdff27a95ba25ce7c829d76b70bc8e6982e148b7d7ea11
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / hornero-0.4.0.post1001-py3-none-any.whl

Download URL hornero-0.4.0.post1001-py3-none-any.whl
Size 158.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e0548ec9cd0432cb894d1e18bc5766cff2000a1aee872c2c388bba925f9cb02e
BLAKE2b-256 checksum
How to use checksums
a37e366be672513bc8eb9da742b4b57c9e43bf537b1f9fc9b3d03149f8526b19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Security for hornero 0.4.0.post1001

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hornero-0.4.0.post1001.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page