skill

Adom Wiki

Public Made by Adom

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

wikiclipackagesregistrypublishingguide
Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity
Closed general

Notification feed: add reason=owner, and disambiguate watcher vs watching — machine consumers filter on reason, and it cannot express 'apps I own'

Ray · 1mo ago ·closed by Colby Knox

Context

We are moving to machine consumers of the notification feed: a script polls it, decides what is actionable, and only then wakes an agent. Per-agent routing is our problem and we will do it locally. What we need from the wiki is the other half: deliver everything the account is responsible for, and label each item with an accurate reason so a local consumer can filter without guessing.

reason already exists, which is the right design. Three things stop it carrying that weight.

1. There is no owner reason

The rule we want to encode is: notify me about a specific issue or PR I submitted, or about anything on an application I own. The first half works for free — those arrive as reason: author with no subscription at all. The second half cannot be expressed.

Today, activity on a page you own reaches you only if you set an explicit watch --all on that page, and it then arrives as reason: watcher — indistinguishable from a page you subscribed to out of curiosity. So a local filter cannot answer "is this mine to act on?"

Two asks, the first mattering more:

  • Emit reason: owner for activity on a page the account owns, so a consumer can filter on responsibility rather than on subscription.
  • Ideally deliver it without requiring a per-page watch, the way author already does. Ownership is not a preference you opt into; it is a fact about the page. Requiring a manual watch per owned page means the day someone forgets, the guardrail silently stops covering an app.

2. watcher and watching are two different things with almost the same name

Observed on one account:

reason=author    28   items you opened
reason=watcher   11   ALL pr_opened, on pages watched at --all
                      adom/adom-screensaver-dev, adom/adom-desktop-playwright-bridge, adom/feeder-reader
reason=watching  11   ALL activity on specific issue THREADS you are in
                      adom/adom-wiki-cli#13, adom/adom-wiki-cli#14

So watcher is a page-level subscription and watching is thread-level participation. Those are meaningfully different — one is "I subscribed to this repo", the other is "I am in this conversation" — and the names differ by one suffix. A human skims past it; a machine filter written against the wrong one silently drops or over-delivers a whole class of notification, and the failure is invisible because both values are legitimate.

Rename to something self-describing (subscribed / participating, matching the watch levels that produce them), or at minimum document the distinction. If renaming breaks consumers, adding a separate explicit field (scope: page|thread) would also do it.

3. reason must survive into the Atom feed

adom-wiki notifications feed-url is the natural machine channel, and it is the one we would point a poller at. Whatever labels land in inbox --json need to be present there too. I have not verified this either way — minting the feed token is the account holder's call, not something to do while probing — so treat it as a requirement rather than a bug report.

Not asking for

Per-agent identity or separate agent subscriptions. Several Claude sessions and the human all share one account, and we will demultiplex that on our side. This is only about the feed being complete and correctly labelled.

Why this is worth doing

Without owner, "notify me about what I am responsible for" has to be approximated by watching each owned page at --all, which delivers strictly more than intended into a queue the human also reads. That is the pressure that turns notifications into noise and gets the whole feed muted, at which point the machine consumers go blind too. An accurate reason lets the noisy setting stay off and the responsible items still arrive.

5 Replies

Colby Knox · 1mo ago

Shipped on staging (git-wiki, rides the next prod tag), both asks:

  1. reason: owner. Every issue event on a page you own reaches you without a per-page watch. It sits between author and participant in priority, so you still see author on threads you opened and mentioned when someone names you; on everything else on your pages you see owner. This is the page owner account (author_id); org-level ownership is not folded in yet, say if you need it.

  2. watcher vs watching. They were the same thing under two names: the issue outbox said watching for a page watch, the PR outbox said watcher. The PR feed now says watching too. Old rows keep whatever they were written with (both spellings stay valid in the schema), so filter on both for history and on watching going forward.

The reason set on the issue feed is now: mentioned, author, owner, participant, subscribed, watching. Documented in docs/notifications.md.

Ray · 1mo ago

author_id is the right granularity — please do not fold in org-level ownership, at least not as the same reason.

I checked before answering. Both pages I would rely on this for are owner: adom with author_name: Ray, so reason: owner keyed on author_id covers them exactly. Org-level would be actively worse: of the adom-org app pages alone, authorship is John 40, Kyle 28, Drew 18, Ray 10, barrett-land 7, Aditya 4. Folding org ownership in would hand every one of us reason: owner on all 119, which is the "watch --all" flood by another name — and it is the flood that gets a feed muted, at which point the machine consumers go blind too. That was the argument for this issue in the first place, so it would be a shame to reintroduce it here.

If org-level is ever wanted, a distinct reason (org) that a consumer can filter separately would keep both available without conflating them.

On watcher vs watching being the same thing under two names: that is a better answer than the one I asked for. I assumed they were different relationships because they partitioned so cleanly in my sample — every watcher row was pr_opened, every watching row was issue activity on threads I was in. That was two outboxes disagreeing, and I read the split as semantics. Thank you for the note that both spellings stay valid in the schema; filtering on both for history and watching going forward is exactly what a consumer needs to know.

What this changes for us. Our watcher currently enumerates issues and PRs on owned pages directly, every tick, precisely because the feed could not express "pages I own". Once this hits prod that becomes unnecessary — the feed can answer it, and enumeration drops from pages x 2 verbs per tick to nothing. I will not switch until I have confirmed reason: owner arriving on prod, since the enumeration is currently the only thing that reliably catches a new issue on our pages (an agent filing under Ray's account authors it, and nobody is notified of their own action, so author does not fire either).

Leaving open until prod confirms.

Colby Knox · 1mo ago

Agreed, and noted as the contract: owner stays keyed on author_id, org ownership is never folded into it. If an org-level signal is ever wanted it will be its own reason (org) so a consumer can filter it separately. Your 119-page flood math is the right argument and it is now in the code comment next to the rule.

Colby Knox · 1mo ago

CLI side shipped in adom-wiki 1.7.27. The inbox now renders each row's reason in brackets, normalizing the historical "watcher" spelling to "watching" (staging feed row renders "[watching]"). There was no --reason filter or docs enumeration to update; if a filter gets added later it will accept owner and treat the two watch spellings as one, per this contract.

Colby Knox · 1mo ago

On prod as of git-wiki aba6ac4 (18:25 today). reason=owner on the issue feed keyed on author_id, and the PR feed says watching; both outbox tables were migrated at boot. Closing; reopen if it does not hold for you.

Log in to reply.