taskuary 0.2.0__py3-none-any.whl

taskuary/devtools.py

@@ -0,0 +1,352 @@
+"""Developer-tool inboxes: GitLab, Azure DevOps, Linear, Trello, Notion, Discord, Sentry
+and PagerDuty as trigger channels - same shape as pm.py. The item that matters is the one
+POINTED AT YOU (assigned issue/MR/work item/card, a new unresolved error, an open incident,
+a message in a watched channel); it lands on the Timeline and goes through the same triage
+as mail. Each polls its own API with the owner's token; only Discord can carry a reply back
+(a bot may post) - everything else is read-only by nature.
+"""
+import json
+from datetime import datetime
+import requests
+from loguru import logger
+
+from .pm import CAP, _cfg, _seed_source, _stamp
+
+
+def _die(r, who, hint):
+    if r.status_code in (401, 403): raise RuntimeError(f'{who} said {r.status_code} - {hint}')
+    r.raise_for_status()
+
+
+def _new(since): return since.strftime('%Y-%m-%d %H:%M:%S')     # local wall-clock floor
+
+
+# ── GitLab ───────────────────────────────────────────────────────────────────────────────
+def _gitlab(c, path, **params):
+    base = (_cfg(c).get('base_url') or 'https://gitlab.com').strip().rstrip('/')
+    r = requests.get(f'{base}/api/v4{path}', params=params, timeout=30,
+                     headers={'PRIVATE-TOKEN': c.get('Secret') or ''})
+    _die(r, 'GitLab', 'check the Personal Access Token (scope: read_api)')
+    return r.json()
+
+
+def test_gitlab(store, c) -> str:
+    if not c.get('Secret'): raise RuntimeError('no token saved - GitLab: avatar → Preferences → Access tokens (scope read_api)')
+    me = _gitlab(c, '/user')
+    host = (_cfg(c).get('base_url') or 'https://gitlab.com').split('//', 1)[-1].rstrip('/')
+    _seed_source(store, c, host)
+    return f"authenticated as {me.get('name') or me.get('username')} on {host} - issues and MRs assigned to you flow in on the next sync"
+
+
+def poll_gitlab(store, c, since, llm=None, file_only=False) -> int:
+    from .ingest import ingest_message
+    after, n = since.astimezone().isoformat(), 0
+    items = ([('issue', i) for i in _gitlab(c, '/issues', scope='assigned_to_me', updated_after=after, per_page=CAP)]
+             + [('merge request', m) for m in _gitlab(c, '/merge_requests', scope='assigned_to_me', updated_after=after, per_page=CAP)])
+    for kind, i in items:
+        who = (i.get('author') or {})
+        proj = '/'.join(str(i.get('web_url') or '').split('/')[3:5]) or 'GitLab'
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"gitlab:{kind[0]}{i['id']}", 'channel': 'gitlab',
+            'subject': f"{'!' if kind[0] == 'm' else '#'}{i.get('iid')} {i.get('title') or ''}".strip(),
+            'body': f"[GitLab {kind} in {proj} - state {i.get('state')} - assigned to you]\n"
+                    f"{str(i.get('description') or '(no description)')[:20000]}",
+            'from_name': who.get('name') or 'GitLab', 'conversation_id': f"gitlab:{kind[0]}{i['id']}",
+            'sent_at': _stamp(i.get('updated_at')), 'source_link': i.get('web_url'), 'source_name': proj}, llm=llm)
+        n += out['status'] != 'duplicate'
+    return n
+
+
+# ── Azure DevOps ─────────────────────────────────────────────────────────────────────────
+def _azdo_base(c) -> str:
+    org = (_cfg(c).get('org_url') or '').strip().rstrip('/')
+    if not org: raise RuntimeError('no organization URL set - enter https://dev.azure.com/yourorg under Credentials')
+    return org if org.startswith('http') else f'https://dev.azure.com/{org}'
+
+
+def _azdo(c, method, path, **kw):
+    r = requests.request(method, f'{_azdo_base(c)}{path}', timeout=30, auth=('', c.get('Secret') or ''), **kw)
+    _die(r, 'Azure DevOps', 'check the PAT (scope: Work Items read)')
+    return r.json()
+
+
+def test_azdo(store, c) -> str:
+    if not c.get('Secret'): raise RuntimeError('no PAT saved - Azure DevOps: User settings → Personal access tokens (Work Items: Read)')
+    j = _azdo(c, 'get', '/_apis/projects?api-version=7.0')
+    _seed_source(store, c, _azdo_base(c).split('//', 1)[-1])
+    return f"authenticated - {j.get('count', 0)} project(s) visible - work items assigned to you flow in on the next sync"
+
+
+def poll_azdo(store, c, since, llm=None, file_only=False) -> int:
+    from .ingest import ingest_message
+    # WIQL dates are day-precision, so the query over-fetches and the watermark filters below
+    wiql = ("Select [System.Id] From WorkItems Where [System.AssignedTo] = @Me "
+            f"And [System.ChangedDate] >= '{since.strftime('%Y-%m-%d')}' Order By [System.ChangedDate] Asc")
+    ids = [str(w['id']) for w in _azdo(c, 'post', '/_apis/wit/wiql?api-version=7.0', json={'query': wiql}).get('workItems') or []][:CAP]
+    if not ids: return 0
+    j = _azdo(c, 'get', f"/_apis/wit/workitems?ids={','.join(ids)}&api-version=7.0")
+    base, n = _azdo_base(c), 0
+    for w in j.get('value') or []:
+        f = w.get('fields') or {}
+        if _stamp(f.get('System.ChangedDate')) < _new(since): continue
+        proj = f.get('System.TeamProject') or ''
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"azdo:{w['id']}", 'channel': 'azdo',
+            'subject': f"#{w['id']} {f.get('System.Title') or ''}".strip(),
+            'body': f"[Azure DevOps {f.get('System.WorkItemType') or 'work item'} in {proj} - "
+                    f"state {f.get('System.State')} - assigned to you]\n"
+                    f"{str(f.get('System.Description') or '(no description)')[:20000]}",
+            'from_name': ((f.get('System.CreatedBy') or {}).get('displayName')
+                          if isinstance(f.get('System.CreatedBy'), dict) else f.get('System.CreatedBy')) or 'Azure DevOps',
+            'conversation_id': f"azdo:{w['id']}", 'sent_at': _stamp(f.get('System.ChangedDate')),
+            'source_link': f'{base}/{proj}/_workitems/edit/{w["id"]}', 'source_name': proj or 'Azure DevOps'}, llm=llm)
+        n += out['status'] != 'duplicate'
+    return n
+
+
+# ── Linear ───────────────────────────────────────────────────────────────────────────────
+def _linear(c, query: str):
+    r = requests.post('https://api.linear.app/graphql', json={'query': query}, timeout=30,
+                      headers={'Authorization': c.get('Secret') or ''})
+    _die(r, 'Linear', 'check the API key (Settings → Security & access → Personal API keys)')
+    j = r.json()
+    if j.get('errors'): raise RuntimeError(f"linear: {j['errors'][0].get('message') or j['errors']}")
+    return j['data']
+
+
+def test_linear(store, c) -> str:
+    if not c.get('Secret'): raise RuntimeError('no API key saved - Linear: Settings → Security & access → Personal API keys')
+    me = _linear(c, '{ viewer { name email } }')['viewer']
+    _seed_source(store, c, me.get('name') or 'Linear')
+    return f"authenticated as {me.get('name')} - issues assigned to you flow in on the next sync"
+
+
+def poll_linear(store, c, since, llm=None, file_only=False) -> int:
+    from .ingest import ingest_message
+    iso = since.astimezone().isoformat()
+    data = _linear(c, '{ issues(filter: {assignee: {isMe: {eq: true}}, updatedAt: {gt: "%s"}}, first: %d) '
+                      '{ nodes { identifier title description url updatedAt state { name } '
+                      'creator { name } project { name } } } }' % (iso, CAP))
+    n = 0
+    for i in (data.get('issues') or {}).get('nodes') or []:
+        proj = (i.get('project') or {}).get('name')
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"linear:{i['identifier']}", 'channel': 'linear',
+            'subject': f"{i['identifier']} {i.get('title') or ''}".strip(),
+            'body': f"[Linear issue{f' in {proj}' if proj else ''} - state {((i.get('state') or {}).get('name'))} - assigned to you]\n"
+                    f"{str(i.get('description') or '(no description)')[:20000]}",
+            'from_name': ((i.get('creator') or {}).get('name')) or 'Linear',
+            'conversation_id': f"linear:{i['identifier']}", 'sent_at': _stamp(i.get('updatedAt')),
+            'source_link': i.get('url'), 'source_name': proj or 'Linear'}, llm=llm)
+        n += out['status'] != 'duplicate'
+    return n
+
+
+# ── Trello ───────────────────────────────────────────────────────────────────────────────
+def _trello(c, path, **params):
+    r = requests.get(f'https://api.trello.com/1{path}', timeout=30,
+                     params={**params, 'key': _cfg(c).get('api_key') or '', 'token': c.get('Secret') or ''})
+    _die(r, 'Trello', 'check the API key + token (trello.com/power-ups/admin → API key → Token)')
+    return r.json()
+
+
+def test_trello(store, c) -> str:
+    if not (_cfg(c).get('api_key') and c.get('Secret')):
+        raise RuntimeError('need the API key (under Credentials) AND the token (write-only) - trello.com/power-ups/admin')
+    me = _trello(c, '/members/me', fields='fullName,username')
+    _seed_source(store, c, me.get('fullName') or me.get('username') or 'Trello')
+    return f"authenticated as {me.get('fullName') or me.get('username')} - cards assigned to you flow in on the next sync"
+
+
+def poll_trello(store, c, since, llm=None, file_only=False) -> int:
+    from .ingest import ingest_message
+    cards = _trello(c, '/members/me/cards', filter='open',
+                    fields='name,desc,dateLastActivity,url,idBoard', boards='open', board_fields='name')
+    n = 0
+    for t in cards[:200]:
+        if _stamp(t.get('dateLastActivity')) < _new(since): continue
+        board = ((t.get('board') or {}).get('name')) or 'Trello'
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"trello:{t['id']}", 'channel': 'trello',
+            'subject': (t.get('name') or '').strip() or 'Trello card',
+            'body': f"[Trello card on \"{board}\" - assigned to you]\n{str(t.get('desc') or '(no description)')[:20000]}",
+            'from_name': 'Trello', 'conversation_id': f"trello:{t['id']}",
+            'sent_at': _stamp(t.get('dateLastActivity')), 'source_link': t.get('url'), 'source_name': board}, llm=llm)
+        n += out['status'] != 'duplicate'
+    return n
+
+
+# ── Notion ───────────────────────────────────────────────────────────────────────────────
+def _notion(c, method, path, **kw):
+    r = requests.request(method, f'https://api.notion.com/v1{path}', timeout=30,
+                         headers={'Authorization': f"Bearer {c.get('Secret') or ''}", 'Notion-Version': '2022-06-28'}, **kw)
+    _die(r, 'Notion', 'check the integration secret (notion.so/my-integrations) - and share the pages with the integration')
+    return r.json()
+
+
+def _notion_title(page) -> str:
+    for p in (page.get('properties') or {}).values():
+        if p.get('type') == 'title':
+            return ''.join(t.get('plain_text') or '' for t in p.get('title') or []) or 'Untitled'
+    return 'Untitled'
+
+
+def test_notion(store, c) -> str:
+    if not c.get('Secret'): raise RuntimeError('no integration secret saved - create one at notion.so/my-integrations, then share pages with it')
+    me = _notion(c, 'get', '/users/me')
+    _seed_source(store, c, me.get('name') or 'Notion')
+    return (f"authenticated as {me.get('name') or 'the integration'} - pages shared with it show on the "
+            'Timeline as they change (a feed: Notion edits are information, not assignments)')
+
+
+def poll_notion(store, c, since, llm=None, file_only=False) -> int:
+    from .ingest import ingest_message
+    j = _notion(c, 'post', '/search', json={'filter': {'property': 'object', 'value': 'page'},
+                                            'sort': {'direction': 'descending', 'timestamp': 'last_edited_time'},
+                                            'page_size': CAP})
+    n = 0
+    for p in j.get('results') or []:
+        at = _stamp(p.get('last_edited_time'))
+        if at < _new(since): continue
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"notion:{p['id']}:{str(p.get('last_edited_time') or '')[:16]}", 'channel': 'notion',
+            'subject': _notion_title(p), 'body': f'[Notion page edited]\n{p.get("url") or ""}',
+            'from_name': 'Notion', 'conversation_id': f"notion:{p['id']}",
+            'sent_at': at, 'source_link': p.get('url'), 'source_name': 'Notion'}, llm=llm)
+        n += out['status'] != 'duplicate'
+    return n
+
+
+# ── Discord ──────────────────────────────────────────────────────────────────────────────
+DISCORD = 'https://discord.com/api/v10'
+
+def _discord(c, method, path, **kw):
+    r = requests.request(method, f'{DISCORD}{path}', timeout=30,
+                         headers={'Authorization': f"Bot {c.get('Secret') or ''}"}, **kw)
+    _die(r, 'Discord', 'check the bot token - and the bot needs the Message Content intent plus access to the channel')
+    return r.json()
+
+
+def test_discord(store, c) -> str:
+    if not c.get('Secret'): raise RuntimeError('no bot token saved - discord.com/developers → your app → Bot → Reset Token')
+    me = _discord(c, 'get', '/users/@me')
+    return (f"authenticated as {me.get('username')} - add channel IDs under Sources "
+            '(right-click a channel → Copy Channel ID, with Developer Mode on)')
+
+
+def poll_discord(store, c, src, since, llm=None, file_only=False) -> int:
+    """Per-source, like Slack: each watched channel id is one source."""
+    from .ingest import ingest_message
+    msgs = _discord(c, 'get', f"/channels/{src['Address']}/messages", params={'limit': CAP})
+    n = 0
+    for m in reversed(msgs if isinstance(msgs, list) else []):
+        if (m.get('author') or {}).get('bot'): continue
+        at = _stamp(m.get('timestamp'))
+        if at < _new(since) or not (m.get('content') or '').strip(): continue
+        who = m.get('author') or {}
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"discord:{m['id']}", 'channel': 'discord',
+            'subject': None, 'body': m.get('content'),
+            'from_name': who.get('global_name') or who.get('username') or 'Discord',
+            'conversation_id': f"discord:{src['Address']}", 'sent_at': at,
+            'source_name': src['Address']}, llm=llm)
+        n += out['status'] != 'duplicate'
+    return n
+
+
+def discord_send(store, channel_id: str, body: str) -> dict:
+    c = store.get_connector_by_type('discord', with_secret=True)
+    if not (c and c.get('Secret')): raise RuntimeError('no Discord bot token saved')
+    _discord(c, 'post', f'/channels/{channel_id}/messages', json={'content': body[:2000]})
+    return {'channel': 'discord', 'chat': channel_id}
+
+
+# ── Sentry ───────────────────────────────────────────────────────────────────────────────
+def _sentry(c, path, **params):
+    base = (_cfg(c).get('base_url') or 'https://sentry.io').strip().rstrip('/')
+    r = requests.get(f'{base}{path}', params=params, timeout=30,
+                     headers={'Authorization': f"Bearer {c.get('Secret') or ''}"})
+    _die(r, 'Sentry', 'check the auth token (Settings → Auth Tokens; scopes org:read + event:read)')
+    return r.json()
+
+
+def _sentry_org(c) -> str:
+    org = (_cfg(c).get('org') or '').strip()
+    if not org: raise RuntimeError('no organization slug set - it is the first path segment of your Sentry URLs')
+    return org
+
+
+def test_sentry(store, c) -> str:
+    if not c.get('Secret'): raise RuntimeError('no auth token saved - Sentry: Settings → Auth Tokens')
+    j = _sentry(c, f'/api/0/organizations/{_sentry_org(c)}/')
+    _seed_source(store, c, j.get('slug') or _sentry_org(c))
+    return f"authenticated to {j.get('name') or j.get('slug')} - new unresolved errors flow in on the next sync"
+
+
+def poll_sentry(store, c, since, llm=None, file_only=False) -> int:
+    from .ingest import ingest_message
+    rows = _sentry(c, f'/api/0/organizations/{_sentry_org(c)}/issues/',
+                   query='is:unresolved', sort='date', limit=CAP, statsPeriod='14d')
+    n = 0
+    for i in rows if isinstance(rows, list) else []:
+        at = _stamp(i.get('lastSeen'))
+        if at < _new(since): continue
+        proj = ((i.get('project') or {}).get('slug')) or 'sentry'
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"sentry:{i['id']}:{at[:16]}", 'channel': 'sentry',
+            'subject': f"{i.get('shortId')} {i.get('title') or ''}".strip(),
+            'body': f"[Sentry {i.get('level') or 'error'} in {proj} - seen {i.get('count')}x, "
+                    f"{i.get('userCount') or 0} user(s)]\n{i.get('culprit') or ''}",
+            'from_name': 'Sentry', 'conversation_id': f"sentry:{i['id']}",
+            'sent_at': at, 'source_link': i.get('permalink'), 'source_name': proj}, llm=llm)
+        n += out['status'] != 'duplicate'
+    return n
+
+
+# ── PagerDuty ────────────────────────────────────────────────────────────────────────────
+def _pagerduty(c, path, **params):
+    r = requests.get(f'https://api.pagerduty.com{path}', params=params, timeout=30,
+                     headers={'Authorization': f"Token token={c.get('Secret') or ''}",
+                              'Content-Type': 'application/json'})
+    _die(r, 'PagerDuty', 'check the API token (Integrations → API Access Keys, or My Profile → User Settings)')
+    return r.json()
+
+
+def test_pagerduty(store, c) -> str:
+    if not c.get('Secret'): raise RuntimeError('no API token saved - PagerDuty: Integrations → API Access Keys')
+    _pagerduty(c, '/incidents', limit=1)
+    _seed_source(store, c, 'PagerDuty')
+    return 'authenticated - open (triggered/acknowledged) incidents flow in on the next sync'
+
+
+def poll_pagerduty(store, c, since, llm=None, file_only=False) -> int:
+    from .ingest import ingest_message
+    j = _pagerduty(c, '/incidents', since=since.astimezone().isoformat(), limit=CAP,
+                   **{'sort_by': 'created_at:asc', 'statuses[]': ['triggered', 'acknowledged']})
+    n = 0
+    for i in j.get('incidents') or []:
+        svc = ((i.get('service') or {}).get('summary')) or 'PagerDuty'
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"pagerduty:{i['id']}", 'channel': 'pagerduty',
+            'subject': f"#{i.get('incident_number')} {i.get('title') or ''}".strip(),
+            'body': f"[PagerDuty incident on {svc} - {i.get('status')} - urgency {i.get('urgency')}]\n"
+                    f"{str(((i.get('body') or {}).get('details')) or i.get('summary') or '')[:20000]}",
+            'from_name': svc, 'conversation_id': f"pagerduty:{i['id']}",
+            'sent_at': _stamp(i.get('created_at')), 'source_link': i.get('html_url'), 'source_name': svc}, llm=llm)
+        n += out['status'] != 'duplicate'
+    return n
+
+
+TESTS = {'gitlab': test_gitlab, 'azdo': test_azdo, 'linear': test_linear, 'trello': test_trello,
+         'notion': test_notion, 'discord': test_discord, 'sentry': test_sentry, 'pagerduty': test_pagerduty}
+POLLS = {'gitlab': poll_gitlab, 'azdo': poll_azdo, 'linear': poll_linear, 'trello': poll_trello,
+         'notion': poll_notion, 'sentry': poll_sentry, 'pagerduty': poll_pagerduty}
+TYPES = tuple(TESTS)
+
+def test(store, c) -> str: return TESTS[c['Type']](store, c)
+
+def poll(store, c, since, llm=None, file_only=False) -> int:
+    try:
+        return POLLS[c['Type']](store, c, since, llm, file_only)
+    except requests.RequestException as e:
+        raise RuntimeError(f"{c['Type']} poll failed: {e}") from e

taskuary/digest.py

@@ -0,0 +1,104 @@
+"""The morning brief's raw material - and the Morning digest REPORT that delivers it.
+
+The digest used to be its own once-a-day machinery writing only the DIGEST.md doc, which
+nobody opened: a brief nobody reads is not a brief. It is a REPORT now (reports.run_digest,
+seeded on first run): the summary lands on the Timeline where mornings actually start, the
+prompt below is edited like any report's on the Reports tab, deleting the source turns the
+whole thing off - and the same run keeps DIGEST.md fresh for the Docs tab.
+"""
+from datetime import datetime, timedelta
+
+DAYS = 3                 # the window the synthesis reads - matches the startup catch-up
+
+# The seeded report's editable instruction - "configure what goes in there" IS this text,
+# on the Reports tab. reports.AI_SYSTEM wraps it; this is only the ask.
+#
+# The two rules at the end are not decoration. A digest once announced "TQ-0032 pending
+# review: approve/send draft 'Re: Resident Refund Request'" when TQ-0032 was a Docker issue
+# and NOTHING was pending: it took a mail subject out of the verdicts block (a "not our
+# task" the owner had already given) and pinned it to a TQ-ref from the open-work list.
+# A brief that invents work waiting on you is worse than no brief, so a ref must arrive
+# wearing the title the data gave it, and an empty section must stay empty.
+PROMPT = (
+    'Write what the owner, half awake, should hold in mind TODAY, under 350 words, grouped into '
+    'sections. Each section is its emoji header on its own line, then tight "- " bullets under it '
+    '(one fact per bullet, tasks named by their TQ-refs), then a blank line. Use exactly these '
+    'sections in this order, and OMIT any with nothing to say:\n'
+    '\U0001f680 In flight — what is being worked and who is waiting on whom\n'
+    '⏳ Waiting on you — questions still unanswered, replies still unapproved\n'
+    '\U0001f4cc Keep honoring — verdicts you gave recently that should keep applying\n'
+    '\U0001f4c8 Patterns — heads-ups (a sender getting louder, the same system failing twice)\n'
+    'Every TQ-ref you write must appear in the data, described with the SAME title it has there - '
+    'never restate a task under another subject, and never carry a subject across from one block '
+    'to another. A block whose data reads "(none)" has nothing to say: omit its section entirely '
+    'rather than filling it.\n'
+    'Never invent facts; no preamble, no sign-off, nothing outside the sections.')
+
+# every prompt ever SHIPPED, so store.__init__ can tell "still the stock text" (upgrade it)
+# from "the owner wrote this" (never touch) - same deal the template docs get
+OLD_PROMPTS = (
+    'Write what the owner, half awake, should hold in mind TODAY, in plain bullets under 350 words:\n'
+    '- what is in flight and who is waiting on whom (name tasks by their TQ-refs)\n'
+    '- questions still unanswered, replies still unapproved\n'
+    '- verdicts the owner gave recently that should keep being honored\n'
+    '- patterns worth a heads-up (a sender getting louder, the same system failing twice)\n'
+    'Never invent facts; omit sections with nothing to say; no preamble, no sign-off.',
+
+    'Write what the owner, half awake, should hold in mind TODAY, under 350 words, grouped into '
+    'sections. Each section is its emoji header on its own line, then tight "- " bullets under it '
+    '(one fact per bullet, tasks named by their TQ-refs), then a blank line. Use exactly these '
+    'sections in this order, and OMIT any with nothing to say:\n'
+    '\U0001f680 In flight — what is being worked and who is waiting on whom\n'
+    '⏳ Waiting on you — questions still unanswered, replies still unapproved\n'
+    '\U0001f4cc Keep honoring — verdicts you gave recently that should keep applying\n'
+    '\U0001f4c8 Patterns — heads-ups (a sender getting louder, the same system failing twice)\n'
+    'Never invent facts; no preamble, no sign-off, nothing outside the sections.',
+)
+
+HEADER = ('# DIGEST.md — your morning brief\n\n'
+          '_Written by the Morning digest report (Reports tab - its prompt decides what goes in\n'
+          "here; deleting the report turns it off). For YOUR eyes - agents get their task's own\n"
+          'context instead. Durable rules belong in Agent memory (Settings) or SOUL.md._\n\n')
+
+
+def _block(out, head, lines):
+    """A header with NOTHING under it is an invitation to fill the silence - the model reads
+    the next block's lines as if they belonged to this one. Say "(none)" out loud instead."""
+    out.append(head)
+    out += list(lines) or ['  (none)']
+
+
+def gather(store, days: int = DAYS) -> str:
+    """The raw material, compact enough to hand an AI whole."""
+    since = (datetime.now() - timedelta(days=days)).isoformat(sep=' ', timespec='seconds')
+    out = []
+    tasks = store.list_tasks()
+    live = [t for t in tasks if t.get('Status') in ('open', 'in_progress', 'waiting')]
+    _block(out, 'OPEN WORK:', (f"  TQ-{t['TaskId']:04d} [{t['Status']}] {t.get('Title') or ''} "
+                               f"(kind {t.get('Kind')}, created {t.get('CreatedAt')})" for t in live[:25]))
+    done = [t for t in tasks if t.get('Status') == 'done' and str(t.get('UpdatedAt') or '') >= since]
+    _block(out, 'FINISHED THIS WINDOW:', (f"  TQ-{t['TaskId']:04d} {t.get('Title') or ''}" for t in done[:20]))
+    # the ref carries its task's TITLE here too (list_reviews already joins it): a line
+    # holding only the attached MAIL SUBJECT let the subject and the ref drift apart, and a
+    # brief that renames a task is a lie in the one place the owner trusts by default
+    _block(out, 'WAITING ON THE OWNER (pending reviews):',
+           (f"  TQ-{r['TaskId']:04d} ({(r.get('Title') or '?')[:60]}) {r.get('Kind')} "
+            f"on mail: {(r.get('Subject') or '(no subject)')[:90]}" for r in store.list_reviews('pending')[:15]))
+    notes = [m for m in store.list_memories() if str(m.get('CreatedAt') or '') >= since]
+    # these quote mail subjects, which is exactly what got recycled into a fake pending
+    # review once - the header says plainly that nothing here is live work
+    _block(out, 'VERDICTS GIVEN THIS WINDOW (already durable in memory - standing rules, NOT open work,\n'
+                'and the mail they quote is already decided):',
+           (f"  [{m.get('Scope')}:{m.get('ScopeKey') or '*'}] {(m.get('Note') or '')[:110]}" for m in notes[:12]))
+    senders = {}
+    for m in store.feed(limit=120, days=days):
+        who = m.get('FromName') or m.get('FromEmail') or m.get('SourceName') or '?'
+        senders[who] = senders.get(who, 0) + 1
+    loud = sorted(senders.items(), key=lambda kv: -kv[1])[:8]
+    _block(out, 'WHO WROTE, HOW OFTEN:', (f'  {who}: {n}' for who, n in loud))
+    return '\n'.join(out)
+
+
+# build_digest / refresh_if_stale used to live here - their whole job (schedule, AI pass,
+# no-AI fallback, filing) is what the reports pipeline already does, so the Morning digest
+# report replaced them: reports.run_digest is the executor, run_report_source keeps the doc.

taskuary/docsync.py

@@ -0,0 +1,124 @@
+"""Operator-doc automation: the docs are the agents' constitution, so connector changes
+write themselves in. Two mechanisms, both non-destructive to hand-written prose:
+- a marker-fenced 'Connected systems' block in SOUL.md, rebuilt on every connector/source
+  change (only the fenced block is touched);
+- the GitHub repository map: discovery only ADDS lines for
+  repos missing from the doc, so per-repo notes the owner wrote are preserved.
+"""
+import json
+
+CONN_START, CONN_END = '<!-- connections:start -->', '<!-- connections:end -->'
+REPO_MAP_HEADER = '## Repository map'
+# The poller's own map, not a second copy of it. This used to be a hand-kept duplicate that
+# stopped at monday, so every connector added after it (gitlab, azdo, linear, trello, notion,
+# sentry, pagerduty, aws, azure, and now clickup/todoist) was invisible to the agents: their
+# sources never made it into the SOUL.md 'Connected systems' block.
+from .channels import CH2SRC
+
+
+# The tool blurb used to say "create/update things in it as the work needs" - and an agent
+# handed that read it as licence to open a GitHub issue for every task it worked, duplicating
+# a tracker that already exists. The licence now follows the agent_issues_enabled setting.
+ROLE_TEXT = {'trigger': 'inbound trigger — new items land on the timeline and go through triage',
+             'report': 'scheduled report source'}
+TOOL_TEXT = {'0': 'yours to read, and to create/update things in ONLY when the task explicitly '
+                  'asks for it — never issues or tracker items for your own work: the task is the record',
+             '1': 'yours to use — read from it and create/update things in it as the work needs'}
+
+def role_text(store, role):
+    if role == 'tool': return TOOL_TEXT['1' if store.github_permissions()[0] else '0']
+    return ROLE_TEXT.get(role)
+
+
+def sync_connections(store, actor='system'):
+    from .store import roles_of
+    doc = store.get_doc('soul') or ''
+    if CONN_START not in doc or CONN_END not in doc: return
+    srcs = store.list_sources()
+    lines = []
+    for c in store.list_connectors():
+        if not c['Active']: continue
+        mine = [s['Address'] for s in srcs
+                if s['Channel'] == CH2SRC.get(c['Type']) and s['Active']
+                and (s.get('ConnectorId') in (None, c['ConnectorId']))]
+        # what each connection IS to the agents, not just that it exists
+        what = '; '.join(role_text(store, r) for r in ('trigger', 'tool', 'report') if r in roles_of(c))
+        if mine: lines.append(f"- {c['Name']}: {', '.join(sorted(mine)[:12])}" + (f" — {what}" if what else ''))
+        elif what: lines.append(f"- {c['Name']} — {what}")
+    for s in srcs:
+        if s['Channel'] != 'report' or not s['Active']: continue
+        cfg = json.loads(s.get('ConfigJson') or '{}')
+        sched = ('on startup' if cfg.get('on_startup')
+                 else f"cron {cfg['cron']}" if cfg.get('cron')
+                 else f"every {cfg['every_minutes']}m" if cfg.get('every_minutes')
+                 else f"daily {cfg.get('daily_at', '')}".strip())
+        lines.append(f"- Report \"{cfg.get('title') or s['Address']}\" ({cfg.get('type', 'rest')}, {sched})")
+    # the tool role is only real if the agents know how to reach it - spell out the call
+    if any('tool' in roles_of(c) for c in store.list_connectors() if c['Active']):
+        from . import config
+        srv = config.load().get('server') or {}
+        auth = ' (header X-Taskuary-Token)' if srv.get('token') else ''
+        lines.append(f"- To USE one of the systems above, POST http://{srv.get('host', '127.0.0.1')}:{srv.get('port', 7787)}"
+                     '/api/tools/run{auth} with {"type": "mssql|database|aws|s3_object|cloudwatch_logs|'
+                     'azure|azure_blob|azure_logs|winrm|mcp|rest|sqlite|rss", ...} — '
+                     'saved credentials are filled in for you; the raw output comes back.'.replace('{auth}', auth))
+    block = '\n'.join(lines) or '_(no connections yet — add them in the Connectors tab)_'
+    head, rest = doc.split(CONN_START, 1)
+    _, tail = rest.split(CONN_END, 1)
+    new = f'{head}{CONN_START}\n{block}\n{CONN_END}{tail}'
+    if new != doc: store.save_doc('soul', new, actor)
+
+
+def _readme_blurb(tok, repo, llm) -> str:
+    """No GitHub description? Read the repo's README instead - AI one-liner when an AI
+    connector is up, else the first real prose line."""
+    try:
+        from .github import readme_text
+        txt = readme_text(tok, repo)
+    except Exception:
+        txt = ''
+    if not txt.strip(): return ''
+    if llm:
+        try:
+            return (llm('You describe codebases for a routing table. ONE plain sentence, <25 words, '
+                        'no markdown: what the repository is and does.',
+                        f'Repository {repo} README:\n\n{txt[:5000]}') or '').strip().splitlines()[0][:200]
+        except Exception:
+            pass
+    lines = [l.strip() for l in txt.splitlines()
+             if l.strip() and not l.startswith(('#', '!', '[', '<', '|', '-', '='))]
+    return lines[0][:160] if lines else ''
+
+
+def update_repo_map(store, repos: list, actor='github', tok=None, llm=None):
+    """repos: [{full_name, description, archived}] - append unknown repos under the map
+    header in SOUL.md so EVERY agent knows which repo owns what. Repos without a GitHub
+    description get summarized from their README (AI one-liner when available)."""
+    doc = store.get_doc('soul') or ''
+    have = doc.lower()
+    PLACEHOLDER = 'no description on GitHub - fill me in'
+    def _desc(r):
+        return ((r.get('description') or '').strip()
+                or (tok and _readme_blurb(tok, r['full_name'], llm))
+                or PLACEHOLDER)
+    # re-discovery heals earlier placeholder lines once a README summary is available
+    healed = False
+    for r in repos:
+        old = f"- **{r['full_name']}**: {PLACEHOLDER}"
+        if old in doc:
+            d = _desc(r)
+            if d != PLACEHOLDER: doc, healed = doc.replace(old, f"- **{r['full_name']}**: {d}"), True
+    adds = [f"- **{r['full_name']}**: {_desc(r)}"
+            + (' (archived - do not touch)' if r.get('archived') else '')
+            for r in repos if r['full_name'].lower() not in have]
+    if not adds:
+        if healed: store.save_doc('soul', doc, actor)
+        return
+    if REPO_MAP_HEADER in doc:
+        head, rest = doc.split(REPO_MAP_HEADER, 1)
+        doc = head + REPO_MAP_HEADER + rest.rstrip() + '\n' + '\n'.join(adds) + '\n'
+    else:
+        doc = (doc.rstrip() + f'\n\n{REPO_MAP_HEADER}\n'
+               'Route each coding task to the repo whose purpose matches; when unsure, escalate.\n'
+               + '\n'.join(adds) + '\n')
+    store.save_doc('soul', doc, actor)