bug(templates): sage/scout/scribe ship no .gitignore — every agent created from them is born with 4 hard security findings

[obasilakis]

Summary

Three visible, user-pickable bundled templates — sage, scout, scribe — ship no .gitignore. Every agent created from them is born failing four hard (must-fix) security checks of the compatibility spec (#668), before the user has done anything.

The platform grades agents against docs/agent-validation-spec.md, but nothing grades the templates the platform itself ships.

Evidence

Compatibility report for a freshly created agent (no user changes, agent healthy and running):

status: issues | hard: 5  soft: 8  info: 6

HARD S-001 [Security] .env is not excluded in .gitignore — credentials may be committed
HARD S-002 [Security] .mcp.json is not excluded in .gitignore — injected credentials may be committed
HARD S-004 [Security] .claude/projects/ is not excluded — Claude Code session history would be committed
HARD S-005 [Security] .trinity/ is not excluded — platform runtime state would be committed
soft F-003 [File Structure] .gitignore is missing — secrets may be committed on first sync
soft S-006/S-007/S-008 [Security] runtime dirs / content/ / wildcard secret patterns not excluded

All four hard findings share one root cause: F-003, no .gitignore in the template.

Survey of config/agent-templates/:

• 11 of 31 bundled templates ship no .gitignore
• Of those, 3 are visible (not hidden: true) and therefore user-pickable: sage, scout, scribe
• Each ships only .claude/, CLAUDE.md, template.yaml
• The other 8 are hidden internal fixtures (e.g. test-echo), out of scope here
• The majority of bundled templates (aero-*, claim-verifier, …) do ship a .gitignore, so this is drift, not a missing convention

Impact

The stated risk in the checks themselves is credentials being committed — .env and .mcp.json both live in the agent home, which is the git repo root (#1703). Any agent from these three that later gets git sync enabled has no protection from the template; it depends entirely on the fleet-wide .gitignore merge in git_service._GITIGNORE_PATTERNS at sync time.

Secondary: a new user's first agent shows a red "5 must-fix" banner on the Overview tab, which reads as "the platform shipped me something broken."

Mitigation that already exists

All four hard findings are in the auto-fixable gitignore set (POST /api/agents/{name}/compatibility/fix, #668), so they are one click from resolved per agent. That is probably why this went unnoticed — but it is a per-agent manual step for a defect shipped in the template.

Proposed fix

1. Add a .gitignore to sage, scout, scribe, matching the one the compliant bundled templates already use.
2. Extend the CI guard proposed in refactor(ci): validate every bundled template.yaml declares only what it ships #1655 with one more assertion: every non-hidden bundled template satisfies the hard-severity checks of docs/agent-validation-spec.md that are statically decidable (the .gitignore set and T-002 naming). refactor(ci): validate every bundled template.yaml declares only what it ships #1655 already establishes that no CI validates template.yaml at all and that the runtime compatibility checks are advisory and "cannot fail a build" — this is the same hook, one assertion wider.

Acceptance Criteria

• sage, scout, scribe each ship a .gitignore covering .env, .mcp.json, .claude/projects/, .trinity/, content/, and the wildcard secret patterns
• An agent created from each reports 0 hard compatibility findings on first load
• CI fails if a non-hidden bundled template regresses on the statically-decidable hard checks
• No change to the hidden internal fixtures (they are correctly excluded from the catalog by bug: agent template catalog surfaces internal test/canary fixtures + a broken stub as real templates #1513)

Notes

• Found while testing PR feat(skills): library lifecycle automation — auto-sync, fleet re-inject, removal-on-unassign (abilityai/trinity-enterprise#236) #1883 on a local instance; unrelated to that PR.
• Related: refactor(ci): validate every bundled template.yaml declares only what it ships #1655 (no CI validation of bundled template.yaml — the guard this extends), bug: agent template catalog surfaces internal test/canary fixtures + a broken stub as real templates #1513 (test fixtures hidden from the catalog — why only 3 of the 11 matter), refactor: agent git repo root is $HOME — 22 gitignore patterns exist only to compensate, and every new home-writing feature repeats the dance #1703 (agent git repo root is $HOME, which is why these exclusions are load-bearing).

[vybe]

PR #1936 (draft) implements this. It reaches 0 HARD findings on 11 of the 14 visible bundled templates; the three starters (sage/scout/scribe) go 6 HARD → 2.

Proposing AC#2 be amended, because as written it is not satisfiable by a .gitignore fix — and I don't think it should be.

Why

The two residual findings on the starters are T-004 / T-005 — resources.cpu and resources.memory absent from template.yaml. They have nothing to do with .gitignore hygiene, and "fix" them means pinning a resources: block into the bundled template, which overrides the admin's fleet-wide default (RES-001, PUT /api/settings/agent-defaults/resources).

So satisfying AC#2 literally would make the three default starter templates silently opt out of the operator's own resource policy — to clear a validation finding. That is a product decision (pin vs. inherit), not a hygiene bug, and it arguably points at a spec issue instead: T-004/T-005 should probably skip rather than fail when a template deliberately inherits the fleet default, since "no resources block" is a legitimate and arguably preferable choice for a starter.

The 11 dd-* templates already reach 0 because they happen to pin resources — an existing catalog convention, not a considered decision about the starters.

Proposed amendment

Replace:

• An agent created from each reports 0 hard compatibility findings on first load

with:

• An agent created from each reports 0 hard .gitignore-decidable compatibility findings on first load (S-001, S-002, S-004, S-005), and does not trip G-001
• T-004 / T-005 (resources.cpu / resources.memory) are explicitly out of scope — whether a bundled template should pin resources or inherit the fleet-wide RES-001 default is a separate product decision, tracked separately

The PR's guard waives exactly those two ids and fails if the waiver goes stale, so the residual can't quietly grow.

Two other scope notes from the implementation

The fix covers 14 templates, not 3. The 11 dd-* templates did ship a .gitignore, but its entire content was outputs/ + *.log — covering 0 of the 4 HARD checks. So all 14 visible templates failed identically, not just the 3 named here.

AC#4 rests on a false premise. The issue treats the other 8/11 as out of scope because they're hidden: true, but hiding is not fixing: hidden is read at exactly two sites (catalog parse + catalog filter) and by no resolver, and crud.py has no hidden gate — so a hidden template stays creatable by id and births the same findings. The PR therefore anchors coverage to an explicit GUARDED_TEMPLATES set rather than to a visibility predicate, and notes as a follow-up that the hidden templates remain unguarded — notably local:default, which ships no .gitignore at all and is the inferred template for a template-less manifest entry, making it genuinely user-reachable.

Also worth noting for expectations: the fix is not retroactive. startup.sh copies /template only when .trinity-initialized is absent, so existing agents keep their current .gitignore and are served by the #668 auto-fix and the sync-time merge.

[vybe]

Still live — confirming, 2026-08-03. A product discussion this week briefly headed toward retiring sage/scout/scribe, which would have mooted this issue. That direction was reversed: a fresh install continues to roll out a fleet from the bundled default-system manifest, and those three templates are what it deploys today.

So this is not superseded — it is on the first-install path for every new instance until the manifest's content is replaced. Replacement is tracked privately and is not blocking: this fix is smaller, independent, and worth doing on its own.