# Decision Log

Records key architectural decisions for the Personal Agent OS.

## 2026-06-20: Initial Repo Structure

**Decision:** Created `personal-agent-os` as a single repo under `Tony_tech` org with `projects/`, `knowledge-base/`, `archive/`, `templates/`, `agent-config/`, and `_meta/`.

**Rationale:**
- Single repo over multiple repos: easier for Hermes to search_files across everything, simpler cross-referencing between projects and knowledge
- `archive/` over deletion: git history preserves everything, but active views stay clean
- `_meta/` at root (not under kb): repo-wide conventions and decision log should be immediately discoverable
- No auto-generating tag index in a folder: better to rebuild via cron script periodically

**Migrated from:** `Tony_tech/research/hermes-automation/` into `knowledge-base/automation-blueprints/hermes/`

**Trade-offs accepted:**
- Single repo means one default branch; projects share tag space (mitigated by hierarchical dir names)
- Cron scripts stored in two places: local disk (runs from) and repo (documentation). Must keep in sync.

## 2026-06-20: Daily Brief — Script + Context-From Pattern

**Decision:** Replaced agent-driven web/X search data gathering with a no-agent shell script that fetches free public APIs (wttr.in, HN Firebase, GitHub API).

**Why:** web_search and x_search were silently failing (Firecrawl unconfigured, xAI credits exhausted). The brief was returning `[SILENT]` for weeks.

**Result:** Working brief in <5 minutes, zero API costs, reliable data every tick.

**Cron job ID:** e94447937052
## 2026-07-12: GitHub Excluded from AI News Daily Feed

**Decision:** GitHub repos are excluded from the AI News Daily site feed (`generate_from_athena.py`). Athena still ingests them into `oracle.db` for research; the site generator filters them out.

**Rationale:**
- GitHub entries (repo releases, model cards) are tool announcements, not news events
- They dominated the feed due to high star-velocity scores (GLM-5.2, DeepSeek-R1, etc.)
- A "Breaking" tag on a repo release violates the editorial rule: repos/papers are never breaking
- GitHub was silently reappearing in the feed at least once this week despite prior exclusion — root cause not conclusively identified (possibly a reverted patch, config drift, or manual override)

**Implementation:** `generate_from_athena.py` filters `source IN ('github', 'gitlab', 'huggingface', 'arxiv')` → renders as plain links or drops entirely. This is a runtime filter, not a pipeline-level exclusion — Athena's DB still has the data.

**Trade-offs accepted:**
- Some genuinely interesting repos won't appear on the site (acceptable — site is for news, not discovery)
- If GitHub exclusion is ever reversed, it requires an explicit commit + decision-log entry, not an ad-hoc patch
- Root cause of the silent revert is not conclusively identified; this entry documents the symptom and the fix, not a proven cause

## 2026-07-12: Score-Floor Tiering Replaces Percentile Gates

**Decision:** AI News Daily tiering (breaking/update/normal) uses absolute score floors + rank, not percentile cutoffs. A tier is allowed to be empty if nothing qualifies.

**Rationale:**
- Previous system: `BREAKING_PCT = 0.90` (top 10%), `UPDATE_PCT = 0.75` (next 25%) — this guaranteed something always appeared in each tier regardless of quality
- Result: 6 red + 15 green items in a single run because rank alone forced items into tiers
- New system: `min_score` floor per tier; if nothing clears the bar, the tier is empty
- Tiers must reflect editorial quality, not statistical inevitability

**Implementation:** `config.yaml` defines `tiering.breaking.min_score` and `tiering.update.min_score`. Generator script reads these at runtime. Floors set from real score distribution analysis (see score distribution in oracle.db).

**Trade-offs accepted:**
- Some runs may have zero "Breaking" items — this is correct behavior, not a bug
- Score floors require periodic review as the score distribution evolves

## 2026-07-12: "UPDATE" Text Label Dropped (Color-Only for Tier 2)

**Decision:** Tier 2 (update) items render in green (`#34a83d`) without a "UPDATE | " text prefix. Breaking items retain "Breaking | " prefix.

**Rationale:**
- "UPDATE | " prefix was visually noisy and implied a correction/follow-up relationship that doesn't exist for most tier-2 items
- Green color alone provides sufficient visual distinction from normal (black) and breaking (red)
- Pending a real replacement label if one emerges from editorial review

**Trade-offs accepted:**
- Without a text label, tier-2 distinction is color-only (accessibility trade-off, acceptable for this audience)

## 2026-07-12: Headline Cap Raised to 300 (Ceiling, Not Target)

**Decision:** `MAX_ITEMS` raised from 40 to 300. This is a hard ceiling, not a target — actual count drops via decay, score floors, and source filtering.

**Rationale:**
- Previous cap of 40 was arbitrary and too low for a 24h freshness window
- The real constraint is quality (score floor), not count
- 300 provides headroom for high-signal days while preventing runaway output
- Stories that don't meet the score floor are dropped regardless of count

**Trade-offs accepted:**
- A very high-signal day could theoretically produce 100+ items — editorial review needed if this happens regularly
- The cap is a safety valve, not a design target