taskuary 0.2.0__py3-none-any.whl

taskuary/ingest.py

@@ -0,0 +1,344 @@
+"""Ingest: anything -> the funnel. No vendor connectors baked in - push messages via the
+HTTP API (POST /api/ingest/push) or your own plugin; report connections run on schedule.
+
+Pipeline per message: dedup -> deterministic policy -> route to a task -> intent triage
+(task / reply_only / fyi) -> file or create. Real tasks NEVER get an auto reply-draft:
+answering is the responder's job (reply_only), doing is the coder's.
+"""
+import json, re, threading
+from loguru import logger
+from .routing import route, draft_task_fields
+from .policy import evaluate
+from .triage import classify_intent, heuristic_intent
+from .store import task_ref
+
+
+# What the agent is TOLD about work from each kind of source. An email needs nothing -
+# the mail is the prompt - but a pull request is a judgement call before it is a coding
+# task, and the judging instructions should not depend on whoever typed the dispatch.
+# Both are defaults: the GitHub card's prompt_pr / prompt_issue fields override them, and
+# any other trigger connector can set task_prompt for its own items.
+PR_RULES = (
+    'This task came from a PULL REQUEST, possibly by an outside contributor. Judge it before '
+    'touching anything: does it solve a real problem worth having? Is the change minimal, safe '
+    'and in keeping with the codebase - no license or dependency swaps, nothing touching CI, '
+    'release or security-sensitive files unless that is explicitly the point? Check out the PR '
+    'branch, read the WHOLE diff, run the tests. Do NOT merge, close or push anything: end with '
+    'a clear verdict - accept, request changes (say exactly which), or reject - and your reasons.')
+ISSUE_RULES = (
+    'This task came from a GITHUB ISSUE. Reproduce it first if you can. Judge whether it is a '
+    'real defect or a feature worth building; fix it when the fix is contained and safe, '
+    'otherwise report plainly what it would take and what the risks are.')
+
+
+def source_rules(store, msg: dict) -> str:
+    """The standing instruction for work from this message's source, if its connector has one.
+    Resolution: the message's own source row names its connector (an email can be Outlook OR
+    Gmail); otherwise the channel's type-named connector. GitHub picks PR vs issue rules off
+    the ingest header and falls back to the shipped defaults above."""
+    ch = (msg or {}).get('Channel')
+    if not ch or ch == 'report': return ''
+    src = next((s for s in store.list_sources(active_only=False)
+                if s.get('Channel') == ch and s.get('Address') == msg.get('SourceName')), None)
+    c = (store.get_connector(src['ConnectorId']) if src and src.get('ConnectorId') else None) \
+        or store.get_connector_by_type(ch) or {}
+    try: cfg = json.loads(c.get('ConfigJson') or '{}')
+    except ValueError: cfg = {}
+    if ch == 'github':
+        is_pr = '[pull request by' in str(msg.get('BodyText') or '')[:200]
+        own = str((cfg.get('prompt_pr') if is_pr else cfg.get('prompt_issue')) or '').strip()
+        return own or (PR_RULES if is_pr else ISSUE_RULES)
+    return str(cfg.get('task_prompt') or '').strip()
+
+
+def ingest_message(store, msg: dict, actor: str = 'router', llm=None, file_only: bool = False) -> dict:
+    """file_only = this connection is a FEED, not a trigger: the item is shown on the
+    timeline and nothing else happens to it - no triage, no AI call, no task. It is a
+    cheaper and quieter path than 'ignore', which is a verdict about the message."""
+    if store.message_exists(msg.get('external_id') or ''):
+        return {'status': 'duplicate', 'task_id': None, 'message_id': None}
+    if file_only:
+        mid = store.add_message({**_fields(msg, None), 'Status': 'feed'})
+        store.add_route(mid, None, 'feed', None,
+                        'shown for information - this connection is a feed, not a task trigger', [], 'feed')
+        return {'status': 'feed', 'task_id': None, 'message_id': mid}
+    cfg = store.get_settings()
+    pol = evaluate(msg, store.list_policies(), store.known_sender(msg.get('from_email')),
+                   cfg.get('default_action', 'draft'))
+    if pol['action'] in ('skip', 'ignore'):
+        # skip = stored for dedupe but NEVER shown (flood senders); ignore = shown, no task
+        mid = store.add_message({**_fields(msg, None), 'Status': 'skipped' if pol['action'] == 'skip' else 'ignored'})
+        store.add_route(mid, None, pol['action'], None, f"policy '{pol['rule']}': {pol['reason']}", [], 'policy')
+        return {'status': pol['action'] + ('ped' if pol['action'] == 'skip' else 'd'), 'task_id': None, 'message_id': mid}
+
+    r = route(msg, store.snapshots(), float(cfg.get('attach_threshold', 0.42)))
+    new_rid = None                       # set when a fresh reply task opens a review below
+    if r['decision'] == 'attach':
+        tid = r['task_id']
+        mid = store.add_message(_fields(msg, tid))
+        store.add_comment(tid, actor, 'agent', f"New {msg.get('channel')} from {msg.get('from_email') or 'unknown'}: {msg.get('subject') or ''}")
+        # the classic round trip: the agent asked something, the hub asked the person, and
+        # THIS is their answer arriving on the same thread. With answer_to_agent=auto it is
+        # typed straight into the live session; 'ask' leaves the one-click offer in the
+        # panel; 'off' does neither. A dead session just means False - nothing breaks.
+        if cfg.get('answer_to_agent', 'ask') == 'auto':
+            try:
+                from . import terminal
+                terminal.say_to_task(store, tid, msg, actor)
+            except Exception as e:
+                logger.warning(f'answer_to_agent failed for task {tid}: {e}')
+    else:
+        # AI-gated triage: without an active AI connector, nothing becomes a task on its
+        # own - messages FILE onto the timeline (visible, promotable by hand) instead of
+        # heuristics spraying tasks for every automated notification. Heuristics still
+        # short-circuit the obvious fyi noise before spending an AI call.
+        if cfg.get('intent_classify_enabled', '1') == '1':
+            h = heuristic_intent(msg)
+            if h['intent'] == 'fyi':                     # obvious automated noise: no AI call needed
+                intent = h
+            elif llm is None:
+                mid = store.add_message({**_fields(msg, None), 'Status': 'filed'})
+                store.add_route(mid, None, 'file', None,
+                                'awaiting AI triage - connect an AI connector (Connectors → AI) to classify inbound automatically', [], 'triage')
+                logger.debug(f"ingest: filed (no AI connector) - {msg.get('subject') or ''}")
+                return {'status': 'filed', 'task_id': None, 'message_id': mid}
+            else:
+                fail = {}
+                def _guarded(sys_, usr_):
+                    try:
+                        return llm(sys_, usr_)
+                    except Exception as e:
+                        fail['err'] = str(e)[:200]
+                        raise
+                from .learn import injectable
+                intent = classify_intent(msg, llm=_guarded, soul=store.doc('soul'),
+                                         learned=injectable(store.doc('learned') or ''),
+                                         notes=notes_for(store, msg), images=msg.get('images'),
+                                         system=store.doc('triage'))
+                if fail:
+                    # the AI errored - filing beats the old default-to-task heuristic
+                    mid = store.add_message({**_fields(msg, None), 'Status': 'filed'})
+                    store.add_route(mid, None, 'file', None,
+                                    f"AI triage failed ({fail['err']}) - filed; fix the AI connector and it will classify new mail", [], 'triage')
+                    logger.warning(f"ingest: AI triage failed, filed - {fail['err']}")
+                    return {'status': 'filed', 'task_id': None, 'message_id': mid}
+        else:
+            intent = {'intent': 'task', 'why': ''}
+        if intent['intent'] == 'fyi':
+            mid = store.add_message({**_fields(msg, None), 'Status': 'filed'})
+            store.add_route(mid, None, 'file', None, f"triage: fyi - {intent.get('why') or 'informational'}", [], 'triage')
+            return {'status': 'filed', 'task_id': None, 'message_id': mid}
+        from .outbound import can_reply
+        if intent['intent'] == 'reply_only' and not can_reply(store, msg.get('channel')):
+            # a question on a channel replies are OFF for: filing beats opening a reply task
+            # whose draft could never be sent anywhere (see outbound.can_reply for who decides)
+            ch = msg.get('channel') or 'this channel'
+            why = ('GitHub replies are off (GitHub card)' if ch == 'github'
+                   else f'replies are off for {ch} (Settings → Replies)')
+            mid = store.add_message({**_fields(msg, None), 'Status': 'filed'})
+            store.add_route(mid, None, 'file', None,
+                            f"triage: reply_only - {intent.get('why') or 'a question'} · {why}, "
+                            'so it is filed instead of drafted', [], 'triage')
+            return {'status': 'filed', 'task_id': None, 'message_id': mid}
+        f = draft_task_fields(msg)
+        if intent['intent'] == 'reply_only': f['kind'] = 'reply'
+        tid = store.create_task({'Title': f['title'], 'Summary': f['summary'], 'Kind': f['kind'],
+                                 'Priority': f['priority'], 'Source': msg.get('channel') or 'api',
+                                 'SourceRef': msg.get('source_link')}, actor)
+        store.audit('task', tid, 'create', actor, 'agent', {'from': msg.get('from_email'), 'reason': r['reason']})
+        mid = store.add_message(_fields(msg, tid))
+        # the agents actually pick work up here:
+        # - reply tasks ALWAYS enter the review queue ("needs me"); auto_draft_enabled
+        #   additionally has the responder write the draft in the background
+        # - CODING tasks auto-dispatch to the coder when coder_auto_enabled is on
+        # - anything else that is real work queues as needs-you, for you to route
+        if f['kind'] == 'reply':
+            new_rid = rid = store.add_review({'TaskId': tid, 'MessageId': mid, 'Kind': 'draft', 'Status': 'pending',
+                                              'Reason': f"needs a reply: {intent.get('why') or 'question for you'}"})
+            if cfg.get('auto_draft_enabled') == '1':
+                _spawn(_auto_draft, store, tid, rid)
+        # KIND is the gate, not "anything that is not a reply". This used to dispatch a coding
+        # agent at every non-reply task, so a Teams message about someone's job scope - real
+        # work, no repository anywhere in it - opened a CLI session on a checkout and started
+        # editing code. A coding agent belongs on a coding task; the rest is yours to place.
+        elif f['kind'] == 'coding' and cfg.get('coder_auto_enabled') == '1' and not msg.get('no_auto'):
+            # no_auto = the channel opted out of self-dispatch (github items always do: an
+            # open repo would start an agent per drive-by PR) - the task queues as needs-you
+            _spawn(_auto_code, store, tid)
+    # the route row is the JUDGEMENT's record, and the timeline panel quotes it verbatim: the
+    # verdict leads (what the classifier decided and why), routing explains new-vs-attached,
+    # and the tail says what happened NEXT - "it's a task" without "and who is working it"
+    # answered a question nobody asked
+    reason = r['reason']
+    if r['decision'] != 'attach':
+        act = ('a reply draft goes to Review for you' if f['kind'] == 'reply'
+               else 'not auto-worked: github items queue for you to promote' if msg.get('no_auto')
+               # said per KIND, because the line is read as a promise about what just happened
+               else 'no code in it - it waits on your list, no agent dispatched' if f['kind'] != 'coding'
+               else 'sent to the coding agent' if cfg.get('coder_auto_enabled') == '1'
+               else 'auto-dispatch is off (Settings) - start the session from the task')
+        reason = (f"triage: {intent['intent']}" + (f" - {intent['why']}" if intent.get('why') else '')
+                  + f" · {r['reason']} · {act}")
+    store.add_route(mid, tid, r['decision'], r['score'], reason, r['candidates'], actor)
+    logger.info(f"ingest: {r['decision']} -> {task_ref(tid)}")
+    # the timeline pushed INTO a chat: 'needs_me' pings only what is waiting on YOU - a question
+    # to answer, or a task nobody was dispatched at. A task an agent just started is being
+    # handled; the ping for those comes later, when its reply is drafted (coder.raise_reply).
+    lvl = cfg.get('notify_level') or 'needs_me'
+    # on an attach there was no fresh triage (`f` only exists on create) - the task itself knows
+    kind = f['kind'] if r['decision'] != 'attach' else (store.get_task(tid) or {}).get('Kind')
+    dispatched = kind != 'reply' and cfg.get('coder_auto_enabled') == '1'
+    if lvl == 'all' or (lvl == 'needs_me' and not dispatched):
+        _notify_new(store, msg, tid, mid,
+                    'a question for you' if kind == 'reply' else 'new task on your list', rid=new_rid)
+    return {'status': 'attached' if r['decision'] == 'attach' else 'created', 'task_id': tid, 'message_id': mid}
+
+
+def _notify_new(store, msg: dict, tid, mid, why: str, rid=None):
+    """One short line to the notify channels. With phone approvals on, a question's ping
+    also carries the [rvN] tag so replying in the chat decides it (phone.py). Failure is a
+    log line, never a broken ingest."""
+    from .outbound import notify
+    from .store import task_ref
+    try:
+        who = msg.get('from_name') or msg.get('from_email') or msg.get('source_name') or 'someone'
+        body_head = str(msg.get('body') or '').strip().splitlines()
+        head = msg.get('subject') or (body_head[0][:80] if body_head else '(no subject)')
+        line = f"{task_ref(tid)} - {why}\n{head}\nfrom {who} on {msg.get('channel') or 'api'}"
+        if rid:
+            from .phone import ping_tail
+            line += ping_tail(store, rid, (store.get_review(rid) or {}).get('DraftText'))
+        notify(store, line, about={'Channel': msg.get('channel'), 'ConversationId': msg.get('conversation_id')})
+    except Exception as e:
+        logger.warning(f'notify failed for message {mid}: {e}')
+
+
+def notes_for(store, msg: dict) -> list:
+    """The owner's standing notes that apply to this message - global ones plus anything
+    learned about this sender or their domain. Triage reads them, so a verdict given once
+    ("this kind of mail is not ours") applies to every message like it afterwards."""
+    em = (msg.get('from_email') or '').lower()
+    dom = em.rsplit('@', 1)[-1] if '@' in em else ''
+    return [n['Note'] for n in store.list_memories()
+            if n['Scope'] == 'global'
+            or (n['Scope'] == 'sender' and (n.get('ScopeKey') or '').lower() == em)
+            or (n['Scope'] == 'sender_domain' and (n.get('ScopeKey') or '').lower() == dom)]
+
+
+def task_from_message(store, mid: int, actor: str = 'owner', kind: str = 'coding', assignee: str = None) -> int:
+    """Promote a filed/ignored/report message into a real task: to hand to an agent, or - with
+    `assignee` - to keep on your own list, because plenty of work is real work no agent can do
+    (go into some web app and click the thing). Already-routed messages keep the task they are on."""
+    m = store.get_message(mid)
+    if not m: raise ValueError(f'no message {mid}')
+    if m.get('TaskId'): return m['TaskId']
+    title = (m.get('Subject') or f"{m.get('FromName') or m.get('FromEmail') or m.get('Channel')} message")[:200]
+    tid = store.create_task({'Title': title, 'Summary': str(m.get('BodyText') or '')[:1000], 'Kind': kind,
+                             'Source': m.get('Channel') or 'api', 'SourceRef': m.get('SourceLink'),
+                             **({'Assignee': assignee} if assignee else {})}, actor)
+    store.attach_message(mid, tid)
+    store.add_route(mid, tid, 'create', None,
+                    f"promoted by the owner - {'theirs to do' if assignee else 'to hand it to an agent'}", [], actor)
+    store.audit('task', tid, 'create_from_message', actor, detail={'message_id': mid, 'subject': title})
+    return tid
+
+
+GREETING = re.compile(r'^(hi|hello|hey|dear|good (morning|afternoon|evening))\b', re.I)
+
+def ask_line(body: str) -> str:
+    """The line that carries the ask - never the greeting it opens with."""
+    lines = [l.strip() for l in (body or '').splitlines() if l.strip()]
+    real = [l for l in lines if not GREETING.match(l) and len(l) > 12]
+    return (real or lines or [''])[0][:120]
+
+
+def split_message(store, mid: int, actor: str = 'owner', kind: str = None) -> int:
+    """Pull one message OUT of the task it was threaded onto and give it its own. Two asks
+    that arrived in the same chat are one conversation but two jobs - and an agent sent at
+    the task only ever gets the first one's prompt."""
+    m = store.get_message(mid)
+    if not m: raise ValueError(f'no message {mid}')
+    old = m.get('TaskId')
+    parent = store.get_task(old) if old else None
+    title = (m.get('Subject') or m.get('FromName') or 'message')[:200]
+    body = str(m.get('BodyText') or '')
+    # the ask itself is the title when the subject is just the chat's name every message
+    # shares - and the ask is never the greeting line it opens with
+    if parent and (parent.get('Title') or '').strip().lower() == title.strip().lower():
+        lines = [l.strip() for l in body.splitlines() if l.strip()]
+        greet = re.compile(r'^(hi|hello|hey|dear|good (morning|afternoon|evening))\b', re.I)
+        title = next((l for l in lines if not greet.match(l) and len(l) > 12), lines[0] if lines else title)[:120]
+    tid = store.create_task({'Title': title, 'Summary': body[:2000],
+                             'Kind': kind or (parent or {}).get('Kind') or 'coding',
+                             'Source': m.get('Channel') or 'api', 'SourceRef': m.get('SourceLink')}, actor)
+    store.attach_message(mid, tid)
+    store.add_route(mid, tid, 'create', None,
+                    f'split off {task_ref(old)} - a separate ask in the same thread' if old else 'made its own task',
+                    [], actor)
+    if old: store.add_comment(old, actor, 'human', f'Split "{title}" out into {task_ref(tid)} - unrelated ask.')
+    store.audit('task', tid, 'split_from_message', actor, detail={'message_id': mid, 'from_task': old})
+    return tid
+
+
+def _spawn(fn, *args):
+    threading.Thread(target=fn, args=args, daemon=True).start()
+
+
+AUTO_SESSIONS = 4      # unattended sessions to keep alive at once; past this it waits for you
+
+def _auto_code(store, tid):
+    """Auto-dispatch puts the CLI on the task in a REAL session - the same one you see when
+    you open the task. Nothing runs where you cannot watch it, interrupt it or answer it.
+
+    A task LIKELY to collide with one already being worked in the same checkout queues behind
+    it instead of racing it (affinity routing - the first agent in has control), and a full
+    house queues for the next free slot. Both drain automatically as sessions end - the card
+    on the board says what it is waiting for."""
+    from . import terminal as term, blackboard as bb
+    agent = store.get_settings().get('default_agent') or 'coder'
+    # the note belongs INSIDE the worker: written before the thread started, a task could
+    # claim "auto-dispatched" with no session behind it whenever the process died first
+    if len([t for t in term.SESSIONS.values() if t.alive]) >= AUTO_SESSIONS:
+        store.enqueue_dispatch(tid, None, agent, f'{AUTO_SESSIONS} agent sessions are already live')
+        store.add_comment(tid, 'router', 'agent',
+                          f'Queued: {AUTO_SESSIONS} agent sessions are already live - '
+                          'it starts by itself when one ends.')
+        return
+    try:
+        cwd = bb.target_cwd(store, tid, agent)
+        ps = bb.peers(store, cwd, exclude_tid=tid) if cwd else []
+        if ps:
+            hit, why = bb.likely_overlap(store, tid, ps)
+            if hit:
+                store.enqueue_dispatch(tid, hit['tid'], agent, why or 'likely to touch the same files')
+                store.add_comment(tid, 'router', 'agent',
+                                  f"Queued behind {hit['ref']} \"{hit['title'][:80]}\" - "
+                                  f"{why or 'likely to touch the same files'}. It starts by itself "
+                                  'when that agent finishes.')
+                return
+        term.start_on_task(store, tid, agent, actor='router')
+        store.add_comment(tid, 'router', 'agent', 'auto-started a live coder session (coder_auto_enabled)'
+                          + (f' - told it about the {len(ps)} agent(s) already in the checkout' if ps else ''))
+    except Exception as e:
+        logger.warning(f'auto dispatch failed for task {tid}: {e}')
+        store.add_comment(tid, 'router', 'agent', f'Auto-start failed: {str(e)[:200]}')
+
+
+def _auto_draft(store, tid, rid):
+    """A reply needs an answer, not an agent: the MAIN AI writes it and it waits for approval.
+    A CLI agent named `responder` takes over only if the owner deliberately configured one."""
+    from . import responder
+    try: responder.write_draft(store, tid, rid, actor='auto-draft')
+    except Exception as e:
+        logger.warning(f'auto-draft failed for task {tid}: {e}')
+
+
+def _fields(msg, task_id):
+    from .store import norm_stamp
+    return {'TaskId': task_id, 'ExternalId': msg.get('external_id'), 'ConversationId': msg.get('conversation_id'),
+            'Channel': msg.get('channel') or 'api', 'SourceName': msg.get('source_name'),
+            'Subject': (msg.get('subject') or '')[:500], 'FromName': msg.get('from_name'),
+            # normalized HERE, the one gate every channel funnels through: a UTC ISO stamp from
+            # any single path sorts the whole timeline out of order (see store.norm_stamp)
+            'FromEmail': msg.get('from_email'), 'SentAt': norm_stamp(msg.get('sent_at')),
+            'BodyText': msg.get('body'), 'SourceLink': msg.get('source_link'), 'Status': 'routed'}

taskuary/learn.py

@@ -0,0 +1,181 @@
+"""LEARNED.md - the profile the funnel infers from the owner's verdicts, written by itself.
+
+SOUL.md is what the owner SAYS; LEARNED.md is what they DO. Every explicit correction - a
+draft edited before sending, a reply rejected, a task reclassified, a filed message promoted
+by hand - carries a general lesson about how this person works: what they are responsible
+for, how they write, what deserves a task, who matters. Nobody types those in, so the system
+distills them itself. The design follows where the experience-learning literature agrees:
+ExpeL's counted insights (arxiv 2308.10144), PRELUDE's infer-the-preference-from-the-edit
+(arxiv 2404.15269), Generative Agents' batched reflection with cited evidence (2304.03442).
+
+Two write paths, deliberately different speeds:
+- HOT (learn_from): one cheap LLM call per correction turns the single event into a
+  hypothesis, visible in the doc seconds after the verdict that taught it - explicit
+  corrections are the high-signal minority and deserve immediate weight;
+- REFLECTION (reflect / reflect_if_due): batched and debounced, rewrites the whole doc -
+  only a batch can see cross-episode patterns, promote hypotheses that kept holding, and
+  kill the ones that did not. Implicit signals (drafts approved untouched) are counted
+  ONLY here: individually they are noise, in aggregate they are confirmation.
+
+Hypotheses are never injected into prompts: a pattern seen once is a guess, and a guess in
+a system prompt is a rule. Only promoted sections travel (injectable()) - and rules whose
+effect is to HIDE mail never promote themselves at all: they wait in 'Proposed' for the
+owner, because a wrong ignore-rule silences the very corrections that would revoke it.
+"""
+import re
+from datetime import datetime, timedelta
+from loguru import logger
+
+DOC = 'learned'
+REFLECT_AT = 3           # corrections that trigger a reflection; fewer still reflect daily
+DAYS = 14                # the fallback event window when no reflection has ever run
+HYP_START, HYP_END = '<!-- hypotheses:start -->', '<!-- hypotheses:end -->'
+PROP_START, PROP_END = '<!-- proposed:start -->', '<!-- proposed:end -->'
+_GATED = re.compile(r'\n## [^\n]*\n+<!-- (hypotheses|proposed):start -->.*?<!-- \1:end -->\n?', re.S)
+
+LESSON_SYSTEM = (
+    'You maintain the Hypotheses section of LEARNED.md: patterns Taskuary is testing about how '
+    'its owner works, distilled from their verdicts. You get the current section and ONE new '
+    'event. Return the updated section: markdown bullets only - no headers, no fences, no preamble.\n'
+    '- Infer the GENERAL preference the event reveals: voice and style, what they are responsible '
+    'for, who matters to them, what deserves a task. Never a one-sender rule (standing notes '
+    'handle those) and never a mere restatement of the event.\n'
+    "- Every bullet ends with a tag: [s:N | ev: id,id | seen: date]. A new hypothesis starts at "
+    "s:2 with this event's id as ev. If a bullet already says the same thing, raise its s by 1, "
+    'append the id, update seen - never duplicate. If the event contradicts one, lower its s by 1; '
+    'delete any bullet at s:0.\n'
+    '- Refer to the owner as {{owner_first}} - a placeholder the app fills in.\n'
+    '- A routine event with nothing general in it: return the section unchanged.\n'
+    '- At most 20 bullets, each under 25 words before the tag; drop the weakest first.')
+
+REFLECT_SYSTEM = (
+    'You are the reflection pass over LEARNED.md, the profile Taskuary maintains of how its owner '
+    'works, learned from their verdicts. Rewrite the WHOLE document and return nothing else - no '
+    'fences, no commentary. Rules:\n'
+    '- Lines without a [s:...] tag were written by the owner: keep them byte-for-byte, where they are.\n'
+    '- Apply the evidence: a hypothesis the events confirm gains 1 strength per distinct episode '
+    '(append its ev id); a contradicted one loses 1; s:0 means delete the line.\n'
+    '- Promote a hypothesis into the matching section above only at s:4+ with evidence from 3+ '
+    'episodes across 2+ different people or threads - one hot thread proves nothing general.\n'
+    '- EXCEPTION: a rule whose effect is to hide or auto-file things ("treat X as fyi", "never a '
+    'task") promotes only into "Proposed rules" - hiding is the owner\'s call to approve.\n'
+    '- Add new hypotheses only for patterns 2+ episodes support; singles stay unwritten.\n'
+    '- Never contradict SOUL.md (it outranks this file); never invent facts beyond the events.\n'
+    '- Keep the section headers, all four <!-- --> marker lines, and every {{owner}}-style '
+    'placeholder exactly as they are; keep the whole file under 120 lines.\n'
+    '- End with a footer: _last reflection: date - what changed in a few words_ (replace any old one).')
+
+
+def _today(): return datetime.now().strftime('%Y-%m-%d')
+def _block(doc, a, b): return doc.split(a, 1)[1].split(b, 1)[0].strip() if (a in doc and b in doc) else None
+def _put_block(doc, a, b, body):
+    head, rest = doc.split(a, 1)
+    return f'{head}{a}\n{body.strip()}\n{b}' + rest.split(b, 1)[1]
+def _unfence(s): return re.sub(r'^```\w*\s*$|^```\s*$', '', (s or '').strip(), flags=re.M).strip()
+
+
+def injectable(text: str) -> str:
+    """The doc as prompts should read it: active sections only. Hypotheses and proposed rules
+    are gated out - a tested pattern is knowledge, an untested one is noise in a system prompt."""
+    if not text: return ''
+    out = _GATED.sub('\n', text)
+    for a, b in ((HYP_START, HYP_END), (PROP_START, PROP_END)):   # blocks whose header was hand-edited away
+        if a in out and b in out:
+            head, rest = out.split(a, 1)
+            out = head + rest.split(b, 1)[1]
+    return out.strip()
+
+
+def learn_from(store, event: str, llm=None):
+    """One explicit owner verdict -> the Hypotheses section, updated now. Never raises: a lost
+    lesson costs one observation, a broken decide endpoint costs trust in the whole funnel."""
+    try:
+        cfg = store.get_settings()
+        if cfg.get('learn_enabled', '1') != '1': return
+        try: n = int(cfg.get('learn_pending') or 0) + 1
+        except ValueError: n = 1
+        store.set_setting('learn_pending', str(n), 'learn')       # ticks even with no AI: the first reflection catches up
+        from .llm import build_llm
+        llm = llm or build_llm(store)
+        doc = store.get_doc(DOC) or ''
+        hyp = _block(doc, HYP_START, HYP_END)
+        if llm is None or hyp is None: return
+        out = _unfence(llm(LESSON_SYSTEM, f'(today: {_today()})\n\nCURRENT HYPOTHESES:\n{hyp[:3000]}'
+                                          f'\n\nNEW EVENT:\n{event[:2000]}', max_tokens=700))
+        # a broken answer never lands in the doc - markers inside it would corrupt the block splice
+        if not out or '<!--' in out or len(out) > 6000: return
+        if out != hyp: store.save_doc(DOC, _put_block(doc, HYP_START, HYP_END, out), 'learn')
+        if n >= REFLECT_AT: reflect(store, llm)
+    except Exception as e:
+        logger.warning(f'learning skipped: {e}')
+
+
+def gather(store, since: str) -> str:
+    """The verdict window, compact enough to hand an AI whole: review decisions with the
+    draft-vs-sent texts (the richest style signal there is), the standing notes written in the
+    window, and the owner-made corrections the audit trail carries."""
+    revs = [r for r in store.list_reviews() if str(r.get('DecidedAt') or '') >= since]
+    ok = [r for r in revs if r['Status'] == 'approved']
+    dec = [r for r in revs if r['Status'] in ('edited', 'rejected', 'no_reply')]
+    out = [f'DRAFT VERDICTS: {len(ok)} sent unchanged (each confirms the current voice), {len(dec)} corrected:']
+    for r in dec[:15]:
+        out.append(f"  rv{r['ReviewId']} [{r['Status']}] \"{(r.get('Subject') or r.get('Title') or '')[:70]}\" "
+                   f"from {r.get('FromEmail') or '?'}"
+                   + (f" - owner's note: {str(r['DecideNote'])[:120]}" if r.get('DecideNote') else ''))
+        if r['Status'] == 'edited':
+            out += [f"    DRAFT: {str(r.get('DraftText') or '')[:400]}",
+                    f"    SENT:  {str(r.get('FinalText') or '')[:400]}"]
+    mems = [m for m in store.list_memories() if str(m.get('CreatedAt') or '') >= since and m.get('Source') == 'verdict']
+    if mems:
+        out.append('VERDICT NOTES WRITTEN (already durable - generalize ACROSS them, never copy them):')
+        out += [f"  mem{m['MemoryId']} [{m['Scope']}:{m.get('ScopeKey') or '*'}] {str(m.get('Note') or '')[:140]}" for m in mems[:12]]
+    acts = ('not_a_task_delete', 'not_mine_delete', 'create_from_message', 'split', 'merge')
+    aud = [a for a in store.list_audit(limit=400)
+           if str(a.get('CreatedAt') or '') >= since and a['Action'] in acts and a.get('ActorType') != 'agent']
+    if aud:
+        out.append('OWNER CORRECTIONS (audit trail):')
+        out += [f"  {a['Action']} {a['EntityType']}{a['EntityId']} {str(a.get('Detail') or '')[:120]}" for a in aud[:20]]
+    return '\n'.join(out)
+
+
+def reflect(store, llm=None) -> bool:
+    """The consolidation: whole-doc rewrite against the event window. Modeled on digest.py's
+    gather -> synthesize -> save_doc, but with NO no-AI fallback - a mechanical rewrite of a
+    doc that feeds every prompt would poison them, and the old doc is always a valid answer."""
+    from .llm import build_llm
+    llm = llm or build_llm(store)
+    doc = store.get_doc(DOC) or ''                 # RAW doc: {{owner}} tokens must survive the rewrite
+    if not llm or not doc: return False
+    since = (store.get_settings().get('learn_last_reflect')
+             or (datetime.now() - timedelta(days=DAYS)).isoformat(sep=' ', timespec='seconds'))
+    try:
+        new = _unfence(llm(REFLECT_SYSTEM,
+                           f'(today: {_today()})\n\nCURRENT LEARNED.md:\n{doc[:6000]}\n\n'
+                           f"SOUL.md (context only - it outranks, never contradict it):\n{(store.doc('soul') or '')[:2500]}\n\n"
+                           f'EVENTS SINCE {since}:\n{gather(store, since)[:5000]}', max_tokens=1800))
+    except Exception as e:
+        logger.warning(f'reflection failed: {e}'); return False
+    # the 120-line budget in the prompt is a request; this is the law. A doc past the cap is a
+    # model that ignored its instructions, and an ever-growing LEARNED.md would silently lose
+    # its tail to the injection caps - the old doc is always the better answer than a bloated one.
+    markers = (HYP_START, HYP_END, PROP_START, PROP_END)
+    if not (new.startswith('#') and 200 < len(new) <= 12_000 and new.count('\n') <= 160
+            and all(new.count(m) == 1 for m in markers)):
+        logger.warning('reflection produced an unusable doc - kept the old one'); return False
+    store.save_doc(DOC, new, 'reflect')
+    store.set_setting('learn_pending', '0', 'reflect')
+    store.set_setting('learn_last_reflect', datetime.now().isoformat(sep=' ', timespec='seconds'), 'reflect')
+    logger.info('LEARNED.md reflected')
+    return True
+
+
+def reflect_if_due(store) -> bool:
+    """Startup hook, digest-style: reflect when enough corrections queued (REFLECT_AT triggers
+    it mid-day too, from learn_from), or once a day when at least one did - never on silence."""
+    cfg = store.get_settings()
+    if cfg.get('learn_enabled', '1') != '1': return False
+    try: n = int(cfg.get('learn_pending') or 0)
+    except ValueError: n = 0
+    if n <= 0: return False
+    if n < REFLECT_AT and (cfg.get('learn_last_reflect') or '').startswith(_today()): return False
+    return reflect(store)