docs: spec the triage source-activation model

The sentry live trial surfaced that triage-intake self-activates in every project. The general personal-account plugins are template-synced everywhere, so its probe reads present-everywhere as active-everywhere. The spec captures the fix: general plugins gate on a per-project :TRIAGE_SOURCES: declaration, project-specific plugins stay active by presence, and the activation layer lives in triage-intake Phase 0 so it fixes interactive runs too. DRAFT, pending review. Links a [#B] build task.

1 files changed, 124 insertions, 0 deletions

diff --git a/docs/specs/2026-07-20-triage-source-activation-spec.org b/docs/specs/2026-07-20-triage-source-activation-spec.org
new file mode 100644
index 0000000..f5c339c
--- /dev/null
+++ b/docs/specs/2026-07-20-triage-source-activation-spec.org
@@ -0,0 +1,124 @@
+#+TITLE: Triage Source Activation — Spec
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-07-20
+#+TODO: TODO | DONE
+#+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED
+
+* DRAFT triage source activation
+:PROPERTIES:
+:ID:       af73ef0b-cd1d-46f1-9e1d-62695733a4de
+:END:
+- 2026-07-20 Mon @ 08:43:23 -0500 — drafted during the morning sentry review. The activation model converged live with Craig off the sentry live-trial finding. DRAFT pending his deep read.
+
+* Metadata
+| Status   | draft                                                        |
+|----------+--------------------------------------------------------------|
+| Owner    | Craig Jennings                                               |
+|----------+--------------------------------------------------------------|
+| Reviewer | (spec-review, next session)                                  |
+|----------+--------------------------------------------------------------|
+| Related  | [[file:../../todo.org::*Triage source activation][todo.org — Triage source activation task]]                    |
+|----------+--------------------------------------------------------------|
+
+* Summary
+
+triage-intake should pull only the sources a project has chosen to pull. Today it runs every plugin it can discover, and the general (personal-account) plugins are template-synced into every project, so every project looks like it wants to triage Craig's personal Gmail, cmail, calendar, and Telegram. The fix is one activation layer: a general plugin runs only when the project names it in a =:TRIAGE_SOURCES:= declaration; a project-specific plugin stays active by its presence, which is already a deliberate per-project act. Sentry's pass-3 probe then reads the same signal.
+
+* Problem / Context
+
+The 8-fire sentry live trial (rulesets, 2026-07-20) surfaced this. Sentry's pass 3 probe is "triage source plugins present for this project," and triage-intake discovers sources by globbing =.ai/workflows/triage-intake.*.org= (general, template-synced) plus =.ai/project-workflows/triage-intake.*.org= (project-specific, never synced). Because the general plugins sync into every project, "plugins present" is true everywhere, so the triage pass self-activates in every project — including rulesets, which is not a triage target.
+
+The harm is two-layered, and sentry's existing safety rule only catches one layer. Sentry's pass-3 line says "destructive actions queue; they never fire unattended," which would hold back the trash/mark-read/star hygiene. But triage-intake also reads the accounts and files each Action item to the local =todo.org= as a =:quick:reactive:= task. Reading and filing are not destructive, so nothing queues them. Under sentry, triage would still authenticate to Craig's personal inboxes overnight and file his personal action items into whatever project the fire runs in. Wrong scope, and it touched real accounts to get there.
+
+The same over-pull exists interactively: running triage-intake by hand in rulesets today would pull personal Gmail too. The trial only made the unattended case visible.
+
+Root cause: the model conflates *presence* with *activation*. A plugin has two existing gates — it must be globbed (presence) and pass its =ENABLED= precondition (capability: "is the gmail MCP reachable?"). Neither answers the question the trial exposed: *should this project pull this source?* For the general plugins, presence comes from sync and capability is true on Craig's machine everywhere, so both gates pass in every project.
+
+Asymmetry that shapes the fix: project-specific plugins do not leak. They live in =.ai/project-workflows/=, are never synced, and exist only where someone deliberately dropped one. A project that polls an RSS feed puts an =triage-intake.rss-*.org= plugin there, and it runs in that project and nowhere else. Only the general synced plugins leak. So the missing activation layer only needs to gate the general plugins.
+
+* Goals and Non-Goals
+
+** Goals
+- Per-project source selection: a project pulls exactly the sources it declares, nothing more.
+- Off-limits by default: a general source that a project has not named is never pulled there.
+- Project-specific sources keep working by presence — dropping the plugin is the declaration (Craig's RSS-feed case works unchanged).
+- One fix covers both paths: the activation layer lives in triage-intake, so interactive and unattended (sentry) runs both respect it.
+- Sentry's pass-3 probe reads the same activation signal rather than mere plugin presence.
+
+** Non-Goals
+- No change to the per-plugin =ENABLED= capability check — it stays the "can I reach this source" gate.
+- No change to the four-bucket classification, the digest shape, or the close behavior.
+- No auto-migration across projects. Projects that pull general sources today declare them via handoff; the change never edits another project's config unattended.
+- No new plugin discovery mechanism — the two-directory glob stays.
+
+* Design
+
+** Two plugin classes, one new activation layer
+
+- *Project-specific plugins* (=.ai/project-workflows/triage-intake.*.org=): active by presence. The plugin exists only because the project author put it there, which is itself the per-project declaration. No further gate. This is where a project's own sources live — an RSS feed, a work Linear, a work Slack.
+- *General plugins* (=.ai/workflows/triage-intake.*.org=, template-synced — personal Gmail, cmail, calendar, Telegram, GitHub PRs): active only when the project names the source in its =:TRIAGE_SOURCES:= declaration. Present-but-undeclared means available-not-active: the plugin is on disk, but this project does not pull it.
+
+** The declaration
+
+A line in the project's =.ai/notes.org= Workflow State block, alongside =:COMMIT_AUTONOMY:= and =:LAST_AUDIT:=:
+
+: :TRIAGE_SOURCES: personal-gmail cmail
+
+Space-separated source names matching general-plugin basenames (=personal-gmail=, =cmail=, =personal-calendar=, =telegram=, =github-prs=). Absent or empty means no general sources are active for this project. Project-specific plugins are unaffected by this line — they run regardless, because presence is their declaration.
+
+** triage-intake Phase 0 change
+
+Phase 0 keeps globbing both directories. The loaded-set computation changes: for each *general* plugin, additionally require its basename to appear in =:TRIAGE_SOURCES:=; skip it with an announced reason otherwise ("skipping personal-gmail — not in :TRIAGE_SOURCES:"). Project-specific plugins skip this check. The =ENABLED= capability check still runs on the survivors. The announce-loaded-set block already exists and gains an "inactive (undeclared)" line so the omission stays visible rather than silent — the same anti-silence discipline Phase 0 already enforces.
+
+** Sentry pass-3 probe change
+
+The probe changes from "triage source plugins present" to "the project has at least one active triage source" — any project-specific plugin present, or a non-empty =:TRIAGE_SOURCES:= intersecting the general plugins on disk. rulesets, declaring nothing and owning no project-specific plugin, probe-skips cleanly.
+
+** Migration
+
+Projects that pull general sources today (home, and possibly work) each add a =:TRIAGE_SOURCES:= line, or their triage goes quiet. This is a per-project handoff, not an automated sweep — the change can't safely guess each project's intended source set. Projects that only ever ran project-specific plugins need no migration.
+
+* Decisions
+
+** DONE Activation gates general plugins only; project-specific stay active-by-presence
+CLOSED: [2026-07-20 Mon]
+Converged live with Craig. Project-specific plugins are already per-project (never synced), so they need no gate; only the general synced plugins leak, so only they need a declaration.
+
+** DONE The activation layer lives in triage-intake Phase 0, not only the sentry probe
+CLOSED: [2026-07-20 Mon]
+Placing it in the engine fixes the interactive over-pull too. Sentry inherits the signal rather than reimplementing it.
+
+** DONE Off-limits by default
+CLOSED: [2026-07-20 Mon]
+An undeclared general source is never pulled. Opt-in is explicit; there is no "pull everything discovered" default.
+
+** DONE Migration is per-project handoffs, never an unattended edit of another project's config
+CLOSED: [2026-07-20 Mon]
+The change can't guess a project's intended source set, and cross-project auto-edits violate the boundary rule.
+
+** VERIFY Declaration format — =:TRIAGE_SOURCES:= space-separated basenames in notes.org Workflow State
+Proposed. Mirrors =:COMMIT_AUTONOMY:=. Open sub-questions: does an empty-but-present marker need to differ from an absent one (e.g. "declared none, on purpose" vs "never configured")? Should a project-specific-only project carry the marker at all, or is its absence correct there?
+
+** VERIFY Should interactive triage adopt the same gate, or only unattended?
+Recommended: same gate both paths (one activation layer). Craig to confirm — the alternative is gating only the sentry pass and leaving interactive as run-all-discovered, which is less clean but avoids changing a path he drives by hand.
+
+* Implementation Phases
+
+** Phase 1 — triage-intake Phase 0 activation rule
+Edit =.ai/workflows/triage-intake.org= (canonical =claude-templates/.ai/workflows/= + mirror): add the general-vs-project-specific activation rule to Phase 0, the =:TRIAGE_SOURCES:= read, and the "inactive (undeclared)" announce line. Run sync-check.
+
+** Phase 2 — sentry pass-3 probe
+Edit =.ai/workflows/sentry.org= (canonical + mirror): change the pass-3 probe to "any active triage source present" and note the activation source. Run sync-check.
+
+** Phase 3 — document the declaration
+Document =:TRIAGE_SOURCES:= in the notes.org Workflow State reference (the template =claude-templates/.ai/notes.org= Workflow State block) so new projects see it. Cross-reference from triage-intake.
+
+** Phase 4 — migration handoffs
+=inbox-send= home (and work, if it pulls general sources) the =:TRIAGE_SOURCES:= line each should add, with the reason. No auto-edit.
+
+** Phase 5 — verification
+triage-intake is a workflow (prose), not a script, so there's no bats surface for the activation rule directly. Verify by a scripted check that a project with no declaration loads zero general plugins (a small fixture around the Phase-0 glob-and-filter logic if it's extracted, or a manual-testing checklist entry otherwise). Confirm rulesets probe-skips triage under sentry, and home still pulls its declared sources.
+
+* Prototype / UI
+
+Not applicable — no UI surface.