personal-agent-os/_meta/decision-log.md

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

Trade-offs accepted:

• 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