# horizon

_Status: horizon — explicitly not being built yet; this doc exists to keep these OUT of v1 scope while preserving the design intent — as of 2026-07-16_
_Connects to: [pipeline-stages](pipeline-stages.md), [worktree-parallelism](worktree-parallelism.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_

## Purpose

Parks the ideas that shaped the 2026-07-16 design session but are deliberately excluded
from v1, so they don't get silently reintroduced as scope creep and don't get lost either.
Load this when scoping any future os-sdlc milestone, or when a v1 stage's design seems to be
straining toward one of these — that strain is expected; the boundary is intentional.

## Design

- **Wake-on-trigger.** An issue state change (e.g. label added, ticket moved to "ready")
  wakes the pipeline instead of a human running `/implement` manually. v1 is deliberately
  manual — the factory is developed and iterated within interactive sessions until it's
  trusted to run autonomously. Autonomy is earned the same way [never-ask-twice](never-ask-twice.md)
  describes for individual decisions, applied here to the pipeline's own trigger.
- **Herdr integration** (https://herdr.dev/docs/, socket API at
  https://herdr.dev/docs/socket-api/). A small deterministic controller — no LLM — opens
  panes, starts interactive Claude Code sessions, sends stage prompts (send_keys-style),
  detects completion, reads the result, and triggers the next stage. Rationale: Anthropic
  now charges extra time allotment for headless runs, so driving automated coding through
  headless mode would eat into the allotment the Max plan's coding was bought for; Herdr-driven
  *interactive* sessions bill as normal usage instead, preserving that allotment for other
  purposes (e.g. a future Hermes integration). **Load-bearing unknown to spike before leaning
  on this at all: does the Herdr socket API give reliable "agent finished" detection, or only
  heuristic pane-scraping?** If it's only heuristic scraping, completion-detection false
  positives/negatives could silently corrupt pipeline stage transitions — this needs to be
  proven, not assumed, before Herdr becomes load-bearing infrastructure.
- **Router agent** dispatching tickets to specialized pipelines (chore/bug/feature/hotfix,
  each with a different stage shape). Deferred until v1's single pipeline shape is proven
  insufficient — matches the ladder described in the SecondBrain vault taxonomy note; adding
  a router before it's needed would be exactly the premature-granularity mistake
  [pipeline-stages](pipeline-stages.md) already rejected once (the seam-creator/implementor
  split).
- **Mobbin UX decision-tree seeding.** See [never-ask-twice](never-ask-twice.md) — a
  pre-seeded convention library (mobbin.com) for the UI-flow decision category, letting
  front-end decisions start at `semi` autonomy instead of `hitl`. Horizon because it depends
  on the category-autonomy mechanism existing and being trusted first.
- **End-state vision** (verbatim intent from the user, 2026-07-16): plan alongside the AI in
  one window; when ready, work is delegated, automatically prioritized, decomposed, and
  worked until complete or blocked; blockages are resolved immediately AND minted into
  ADRs/best practices/conventions so that next time the AI confidently picks the obvious path
  or presents a narrowed choice; the factory self-improves over time and agents take agency
  as confidence in their decisions is earned.

## Open questions

- Whether wake-on-trigger and Herdr integration are actually separable milestones (wake-on-trigger
  could plausibly ship without Herdr, using headless mode at the accepted allotment cost) or
  whether they're coupled in practice.
- What "trusted to run autonomously" concretely means as an exit criterion for v1 — likely an
  ask-rate threshold fed by [never-ask-twice](never-ask-twice.md)'s audits, but not yet defined.
- Whether the router-agent ladder rungs (chore/bug/feature/hotfix) match the vault taxonomy
  note's categories exactly or need adjustment once real ticket volume exists.

## Sources

- Herdr docs: https://herdr.dev/docs/, https://herdr.dev/docs/socket-api/
- SecondBrain vault: taxonomy/ladder note (chore/bug/feature/hotfix router categories)
- mobbin.com (design-pattern library)
- ADR-0037
- 2026-07-16 design session (this doc's origin, including verbatim end-state vision)