alissa-tools-github-orcloop 0.3.7__tar.gz → 0.3.8__tar.gz

{alissa_tools_github_orcloop-0.3.7/src/main/alissa_tools_github_orcloop.egg-info → alissa_tools_github_orcloop-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.3.7
+Version: 0.3.8
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_orcloop-0.3.7 → alissa_tools_github_orcloop-0.3.8}/src/main/alissa/tools/github/orcloop/alissa_client.py

@@ -127,6 +127,37 @@ would then hold a task whose only dependency is fully validated -- forever,
 eventually paging ``release-blocked``. Deduplicating matches what the resolved
 view actually does.
 
+TASK CONTEXT ATTACHMENTS (O14)
+==============================
+An operator's decisions about a task do not all fit in the description that was
+written before the work started. Alissa's answer is the task's **context
+attachments** -- ``GET /v1/tasks/<ref>/context`` -> ``{"context": [...]}`` --
+and O14 makes them travel: orcloop renders them into the issue it files, so a
+decision recorded after authoring reaches the implementing worker (repo issue
+#34). Verified live against ``api.alissa.app``:
+
+* Each row carries ``_id``, ``title``, ``createdAt`` (ms), ``actorId``/
+  ``authorName``, and then AT MOST ONE payload of ``markdownContent`` /
+  ``link`` / a vault reference, plus an optional one-line ``note``. The
+  OpenAPI schema pins only ``_id`` and ``title`` (everything else is
+  ``additionalProperties``), so `get_task_context` treats every payload field
+  as optional and an item with none of them still renders as a titled,
+  empty subsection rather than being dropped -- a decision the operator
+  attached and orcloop silently discarded is the one outcome #34 exists to
+  prevent.
+* The task DETAIL payload carries ``contextCount`` (an int), which is what
+  lets the release path skip this read entirely for the common zero-context
+  task -- see `Task.context_count`.
+
+Note for a future reader: the detail payload ALSO embeds the attachments
+themselves under an undocumented ``contextAttachments`` key, so the second
+call could in principle be avoided. orcloop deliberately does not read it. The
+dedicated route is the documented, access-gated one (the OpenAPI ``Task``
+schema pins neither the key nor its item shape), and the release path's
+conservatism depends on being able to tell "there are N attachments" from "I
+read them": a silently-absent embedded array would read as "no context" on
+exactly the payload that declares some.
+
 WHO AM I (O8)
 =============
 ``GET /v1/ping`` -- ``{"pong", "timestamp", "userId", "actorId",
@@ -266,6 +297,29 @@ class Dependency:
     status: str
 
 
+@dataclass(frozen=True)
+class ContextItem:
+    """One knowledge/reference attachment on a task (O14).
+
+    The operator's decision channel: whatever was decided AFTER the task was
+    authored lands here rather than being rewritten into the description. Every
+    field but `id` is optional in the payload, so every one but `id` defaults
+    to empty -- an attachment is identified by its title and rendered from
+    whichever payload it carries.
+
+    `markdown` is the write-up, `link` a bare URL, `note` the one-line "why
+    this is relevant"; an attachment may carry any combination, including none
+    (a vault reference the REST payload does not inline). `created_at` is ms
+    since epoch, 0 when the payload omits it -- the renderer orders on it."""
+
+    id: str
+    title: str = ""
+    markdown: str = ""
+    link: str = ""
+    note: str = ""
+    created_at: int = 0
+
+
 @dataclass(frozen=True)
 class Task:
     """A task as the DETAIL endpoint reports it -- full description and DoD,
@@ -293,6 +347,13 @@ class Task:
     # len(dependencies) when an upstream is invisible to this actor -- the gate
     # treats that mismatch as "not provably clear".
     depends_on_count: int = 0
+    # How many context attachments the DETAIL payload declares (`contextCount`,
+    # O14). Purely a "is the second read worth making" hint for the release
+    # path: 0/absent skips `get_task_context` entirely, which is the common
+    # case. It is NOT a length contract -- attachments can be added or deleted
+    # between the two reads -- so nothing keys on it agreeing with what the
+    # context endpoint returns. Only "declares some" vs "declares none" matters.
+    context_count: int = 0
 
 
 def _query(params: dict) -> str:
@@ -625,6 +686,17 @@ class AlissaClient:
         created_raw = task.get("createdAt")
         created_at = int(created_raw) if isinstance(created_raw, (int, float)) else 0
 
+        # A bool IS an int in Python; `contextCount: true` would read as 1 and
+        # buy a context read on a payload that declared nothing countable, so
+        # it is excluded explicitly. Negatives clamp to 0 -- "fewer than none"
+        # is not a reason to make the read.
+        count_raw = task.get("contextCount")
+        context_count = (
+            max(0, int(count_raw))
+            if isinstance(count_raw, (int, float)) and not isinstance(count_raw, bool)
+            else 0
+        )
+
         number = task.get("taskNumber")
         return Task(
             ref=f"TASK-{number}" if isinstance(number, int) else str(ref),
@@ -638,7 +710,58 @@ class AlissaClient:
             created_at=created_at,
             dependencies=tuple(dependencies),
             depends_on_count=depends_on_count,
+            context_count=context_count,
+        )
+
+    def get_task_context(self, ref: str) -> list[ContextItem]:
+        """The task's context attachments, in the order the endpoint returns
+        them (`GET /v1/tasks/<ref>/context`).
+
+        Ordering is the CALLER's to impose (the renderer sorts on
+        `created_at`); this stays a faithful read of the payload. Rows without
+        an `_id` are dropped -- an attachment that cannot be addressed cannot be
+        cited or edited -- but a row with an id and nothing else is KEPT: the
+        payload pins only `_id` and `title`, so treating a shape this adapter
+        does not recognise as "no context" would drop the very decisions the
+        feature exists to carry.
+
+        A 2xx whose `context` key is not an array is a contract violation, not
+        an empty list, and surfaces as the base `AlissaError` -- the same way
+        `get_task` refuses to fabricate a Task. That distinction is load-
+        bearing on the release path: it holds the release instead of filing an
+        issue that silently lost the operator's decisions.
+        """
+        payload = self._request(
+            "GET", f"/v1/tasks/{urllib.parse.quote(str(ref), safe='')}/context"
         )
+        rows = payload.get("context") if isinstance(payload, dict) else None
+        if not isinstance(rows, list):
+            raise AlissaError(200, f"no context array in response for {ref!r}")
+
+        out: list[ContextItem] = []
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            item_id = row.get("_id")
+            if not isinstance(item_id, str) or not item_id:
+                continue
+            created_raw = row.get("createdAt")
+            out.append(
+                ContextItem(
+                    id=item_id,
+                    title=str(row.get("title") or ""),
+                    markdown=str(row.get("markdownContent") or ""),
+                    link=str(row.get("link") or ""),
+                    note=str(row.get("note") or ""),
+                    created_at=(
+                        int(created_raw)
+                        if isinstance(created_raw, (int, float))
+                        and not isinstance(created_raw, bool)
+                        else 0
+                    ),
+                )
+            )
+        return out
 
     def add_evidence(self, ref: str, title: str, markdown: str, *, item_type: str = "evidence") -> None:
         """Attach an evidence/deliverable item (outputs surface, not context).

{alissa_tools_github_orcloop-0.3.7 → alissa_tools_github_orcloop-0.3.8}/src/main/alissa/tools/github/orcloop/loop.py

@@ -46,10 +46,40 @@ issues the develop daemon can pick up:
 * **Ordering** is priority-then-age: the highest-priority ready task goes
   first, oldest breaking ties, so the queue drains deterministically.
 * **Rendering** is mechanical: the issue body is the task description with its
-  control trailers stripped, then the Definition of Done, an acceptance-criteria
-  checklist, and a canonical trailer block (`Autonomous-Dev`, `Autonomous-Scope`
-  if any, `Alissa-Task:`). The `Autonomous-*` trailers are re-emitted so lane
-  occupancy stays derivable from the open issues themselves.
+  control trailers stripped, then -- since O14 -- the origin task's CONTEXT
+  ATTACHMENTS, then the Definition of Done, an acceptance-criteria checklist,
+  and a canonical trailer block (`Autonomous-Dev`, `Autonomous-Scope` if any,
+  `Alissa-Task:`). The `Autonomous-*` trailers are re-emitted so lane occupancy
+  stays derivable from the open issues themselves.
+* **Context attachments travel** (O14, issue #34). An operator's decisions
+  recorded on a task AFTER it was authored used to reach nobody: the issue body
+  was rendered from description + DoD + criteria, and a worker cannot read the
+  origin task cross-partition. So the release path now reads
+  `GET /v1/tasks/<ref>/context` (skipped entirely when the detail's
+  `contextCount` is 0) and renders a `## Context` section between the
+  description and the DoD. Three properties make it safe to put operator- and
+  third-party-authored text into a body the daemon itself parses:
+
+  - **No line of it can be a trailer.** The canonical block sits at the END of
+    the body while every trailer parser is line-anchored and FIRST-match-wins,
+    so a context line beginning with a control key would silently win over the
+    real one -- retargeting the repo, the scope, or (worst) the origin task the
+    close edge advances on merge. Every such line is blockquoted before it is
+    rendered; see `escape_control_lines` and `control_keys`.
+  - **Loud caps.** Per attachment and per section, both marked in the body with
+    `[context truncated: ...]` and counted onto the release log line, with the
+    section's ceiling computed from what is LEFT under GitHub's 65,536-char
+    issue-body limit.
+  - **Hold, don't guess -- then page.** A task that declares attachments but
+    whose context read fails is HELD for the pass and retried next poll; the
+    rest of the pass proceeds. EVERY read failure holds, not only the transient
+    ones, because a permanent one is equally a release whose decisions did not
+    travel -- and because that widening admits conditions that never
+    self-clear, the hold carries the floor-then-page shape `_dedupe_unreadable`
+    uses rather than holding quietly forever. See `_context_unreadable`.
+
+  Context is a SNAPSHOT taken at release time -- attachments added afterwards
+  do not re-render an open issue.
 * **Create -> ledger -> label**, in that order, with idempotent crash
   completion: the issue is created WITHOUT the trigger label, the ledger row is
   written (`labeled=0`), then the label is stamped (`labeled=1`). The label is
@@ -250,7 +280,8 @@ import time
 from collections import Counter
 from dataclasses import dataclass
 from enum import Enum
-from typing import Callable
+from functools import lru_cache
+from typing import Callable, Sequence
 
 from .alissa_client import (
     AlissaClient,
@@ -258,6 +289,7 @@ from .alissa_client import (
     AlissaTransient,
     BodyOfWork,
     BowMember,
+    ContextItem,
     Task,
 )
 from .config import FEED_BOW, Config
@@ -292,6 +324,60 @@ DEP_CLEAR_STATES = frozenset({"pending_validation", "validated"})
 TASK_TODO_STATE = "committed"
 TASK_IN_FLIGHT_STATE = "in_progress"
 
+# --- the rendered context section (O14, issue #34) -------------------------
+#
+# The third trailer key of the canonical block. Unlike `marker_key`/`scope_key`
+# it is NOT configurable -- `ghclient.TASK_TRAILER_RE` hardcodes it, and both
+# daemons parse it -- so it is a constant here and the renderer emits it from
+# this one place rather than a literal.
+TASK_TRAILER_KEY = "Alissa-Task"
+
+# GitHub refuses an issue body longer than this. Everything the context section
+# adds is bounded against what is left of it.
+GITHUB_BODY_LIMIT = 65536
+
+# The two context caps. Deliberately CONSTANTS, not config keys: issue #34 asks
+# for documented caps, not tunable ones, and a config key is a compatibility
+# commitment. Sized so the common case never notices (a decision write-up is
+# hundreds of chars, not thousands) while a pathological attachment cannot eat
+# the issue: three full-size attachments still leave ~40k for the operator's own
+# description, DoD and criteria. Widening them later is additive.
+CONTEXT_ITEM_MAX_CHARS = 8000
+CONTEXT_SECTION_MAX_CHARS = 24000
+
+CONTEXT_HEADING = "## Context"
+# The two headings `render_issue` emits AFTER the context section. Constants
+# rather than literals because `strip_context_section` terminates the excision
+# on them: renaming a heading at the render site and not the excision site
+# would silently re-open the O13 warning this PR closed, and that is a failure
+# nothing else would catch.
+DOD_HEADING = "## Definition of Done"
+CRITERIA_HEADING = "## Acceptance criteria"
+# The per-attachment subsection heading. Also the structural signature
+# `strip_context_section` anchors the START of the excision on.
+CONTEXT_SUBHEADING = "### "
+# Every truncation marker starts with this, at both levels, so one grep over an
+# issue body answers "did anything get cut".
+CONTEXT_TRUNCATED_PREFIX = "[context truncated:"
+CONTEXT_ESCAPE_PREFIX = "> "
+CONTEXT_UNTITLED = "(untitled attachment)"
+CONTEXT_EMPTY = "_(no inline content — see the attachment on the task)_"
+
+# Marks the one attachment the section may cut mid-block (the first, and only
+# when nothing fits whole). Carries its own separator so the room arithmetic can
+# subtract exactly what appending it costs.
+CONTEXT_PARTIAL_MARKER = (
+    f"\n\n{CONTEXT_TRUNCATED_PREFIX} attachment cut to fit the remaining "
+    f"section budget]"
+)
+
+# The floor under a partial first attachment. When even the first block will not
+# fit whole, it is cut to the room that IS left rather than rendering an empty
+# section -- but only if this much of it survives; below that the "attachment"
+# would be a title and a stub, which tells the worker less than the explicit
+# "0 of N rendered" notice does.
+CONTEXT_MIN_PARTIAL_CHARS = 200
+
 # The close edge only mutates a task the loop itself left in one of these two
 # states. `in_progress` is the NORMAL one since issue #30 -- the release edge
 # sets it the moment the issue exists, so that is how a task in flight reads.
@@ -340,6 +426,18 @@ ESCALATION_DEDUPE_UNREADABLE = "dedupe-unreadable"
 # reach of every prefix read of a page kind.
 DEDUPE_UNREADABLE_SINCE = "marker:dedupe-unreadable"
 
+# The O14 context read could not answer. Same floor-then-page shape, and for the
+# same reason `_dedupe_unreadable` gives: `_release` holds on EVERY `AlissaError`
+# rather than only the transient ones (an issue filed without the operator's
+# decisions cannot be taken back), and both permanent shapes are reachable -- a
+# 403 on the context route for this actor, and the `no context array` contract
+# violation. Neither self-clears, so without a page the task holds forever on an
+# INFO line. The marker measures THE FAILURE, not the task age, for the same
+# reason again: this is a single I/O outcome, so an old task would page on
+# contact with a self-clearing blip and burn the kind.
+ESCALATION_CONTEXT_UNREADABLE = "context-unreadable"
+CONTEXT_UNREADABLE_SINCE = "marker:context-unreadable"
+
 # How many CLOSED trailer matches the pre-create dedupe will walk looking for a
 # merged closing PR. Each check is a bounded timeline walk (see
 # `GitHub.closing_merged_pr`), and the matches are walked newest-first, so this
@@ -478,6 +576,17 @@ DEDUPE_UNREADABLE_COMMENT = (
     "work by hand) to clear it."
 )
 
+CONTEXT_UNREADABLE_COMMENT = (
+    "**Orchestrator: context unreadable** — this task declares "
+    "{count} context attachment(s), and the orchestrator has been unable to "
+    "read them continuously for over {floor_days} day(s): {reason}. The "
+    "release is held rather than file a develop issue WITHOUT the decisions "
+    "recorded on this task, and it will keep retrying. Usual causes: the "
+    "orchestrator's token lost its role on this task, or the context endpoint "
+    "is returning an unexpected shape. Restore the read (or delete the "
+    "attachments if they are no longer needed) to clear it."
+)
+
 ALREADY_MERGED_ISSUE_COMMENT = (
     "**Orchestrator: already merged** — this closed issue carries the "
     "`Alissa-Task:` trailer of a task that is still queued for release. No "
@@ -752,11 +861,18 @@ class Orchestrator:
                 # malformed trailer -- and the two are indistinguishable in
                 # every later line, because from here on the lane only carries
                 # `[]`. Said once per issue per pass, here, where the difference
-                # is still visible. (A released body keeps the operator's prose
+                # is still visible. (A released body keeps the operator's PROSE
                 # verbatim, mid-line fragment and all: `_strip_control_lines`
                 # drops trailers by the same anchored rule, so what was missed
-                # in the task is missed in the issue too.)
-                note = self._malformed_trailer(issue.body, self.config.scope_key)
+                # in the task is missed in the issue too. It does NOT keep only
+                # the operator's prose -- since O14 the body also carries the
+                # rendered context section, whose escaped lines are mid-line
+                # keys orcloop wrote itself. Hence the excision: the warning
+                # must only ever name text a human wrote.)
+                note = self._malformed_trailer(
+                    strip_context_section(issue.body, self.config),
+                    self.config.scope_key,
+                )
                 if note:
                     log.warning(
                         "%s declares no `%s:` trailer, so it occupies the WHOLE "
@@ -1809,8 +1925,12 @@ class Orchestrator:
         # to `_dedupe_result`'s crash-recovery branch rather than back here.
         # What recurs in the malformed-trailer case is the lane hold above,
         # which does carry it.
+        # Context section excised for the same reason as in `_scan_released`:
+        # the issue being adopted may well be one orcloop rendered (a crash
+        # between create and the ledger write leaves exactly that), so its
+        # escaped context lines are mid-line keys the daemon wrote, not a human.
         issue_note = "" if issue_scope else self._malformed_trailer(
-            issue.body, self.config.scope_key
+            strip_context_section(issue.body, self.config), self.config.scope_key
         )
         labeled = self.config.label in issue.labels
         if not labeled:
@@ -2083,6 +2203,136 @@ class Orchestrator:
             if self.state.escalated(task_number, kind):
                 self.state.clear_escalation(task_number, kind)
 
+    def _context_unreadable(self, task: Task, exc: AlissaError) -> tuple[str, Decision]:
+        """The context read could not answer, so the release is HELD rather
+        than degraded -- with the floor-then-page shape `_dedupe_unreadable`
+        uses, and for the identical reason.
+
+        Why hold at all: the attachments are where the operator's
+        post-authoring decisions live (issue #34), so an issue filed without
+        them briefs the worker on a superseded plan. A held pass is recoverable
+        next poll; that is not.
+
+        Why hold on EVERY `AlissaError` and not just `AlissaTransient` as #34
+        specifies: a permanent failure is still a release whose decisions did
+        not travel. Both permanent shapes are reachable -- a 403 on the context
+        route for this actor, and the `no context array` contract violation --
+        and narrowing the catch would put them on the release path with no
+        route at all, which is the worse of the two.
+
+        Why that widening OBLIGES this method: a permanent failure does not
+        self-clear, so without a page the task holds on an INFO line forever
+        and no operator is ever told. Every other unbounded hold in this loop
+        (`release-blocked`, `dedupe-unreadable`) pages past the floor.
+
+        The floor measures THE FAILURE, not the task age -- `_dedupe_unreadable`
+        argues this at length and the argument transfers exactly: this is a
+        single I/O outcome, so an old task would page on contact with a
+        self-clearing blip and burn the kind for the genuine outage later. So
+        the first failure records `marker:context-unreadable` from the loop's
+        own clock and holds quietly; only once THAT is older than
+        `release_blocked_floor_days` does one `context-unreadable` escalation
+        land. `_read_context` clears both rows the moment a read answers.
+
+        The floor knob is shared with the other two on purpose: all three ask
+        "how long may a release be quietly held before an operator is told",
+        and a fourth knob for the same question is a config surface (and a
+        container floor bump) that buys nothing.
+        """
+        floor_seconds = self.config.release_blocked_floor_days * 86400
+        held = (
+            f"context unreadable ({task.context_count} attachment(s) declared): "
+            f"{exc}; held rather than file an issue without the operator's "
+            f"decisions"
+        )
+        rows = self.state.escalations_matching(task.task_number, CONTEXT_UNREADABLE_SINCE)
+        now = int(self._now())
+        if not rows:
+            if not self.config.dry_run:
+                self.state.record_escalation(
+                    task.task_number, CONTEXT_UNREADABLE_SINCE, at=now,
+                )
+            return self._logged(task.ref, Decision(
+                Action.HELD,
+                held + "; first failure, retries next poll",
+                task.task_number,
+            ))
+
+        failing_for = now - int(rows[0]["escalated_at"])
+        if failing_for < floor_seconds:
+            return self._logged(task.ref, Decision(
+                Action.HELD,
+                held + f"; failing for {failing_for // 3600}h, within the "
+                f"{self.config.release_blocked_floor_days}d floor",
+                task.task_number,
+            ))
+
+        self._escalate(
+            task.task_number,
+            ESCALATION_CONTEXT_UNREADABLE,
+            CONTEXT_UNREADABLE_COMMENT.format(
+                count=task.context_count,
+                reason=str(exc),
+                floor_days=self.config.release_blocked_floor_days,
+            ),
+        )
+        return self._logged(task.ref, Decision(
+            Action.ESCALATED,
+            held + f", and failing for {failing_for // 86400}d — past the "
+            f"{self.config.release_blocked_floor_days}d floor",
+            task.task_number,
+        ))
+
+    def _context_answered(self, task_number: int) -> None:
+        """The context read answered, so any recorded failure is OVER: drop the
+        first-seen marker and the page kind together.
+
+        Clearing the page kind is the point, exactly as in `_dedupe_answered`:
+        `_escalate` dedupes per (task, kind), so without a clear a SECOND,
+        unrelated outage would never page. Guarded by a read so the common
+        (working) path does not write on every release."""
+        if self.config.dry_run:
+            return
+        for kind in (CONTEXT_UNREADABLE_SINCE, ESCALATION_CONTEXT_UNREADABLE):
+            if self.state.escalated(task_number, kind):
+                self.state.clear_escalation(task_number, kind)
+
+    def _read_context(self, task: Task) -> list[ContextItem]:
+        """The origin task's context attachments, or [] when it declares none.
+
+        `contextCount` is the skip: a task with 0 (or a payload that omits the
+        key) costs no extra call, which is every task that predates O14 and
+        most that follow. The count is only ever compared against zero -- it is
+        a denormalised counter, the two reads are not atomic, and keying
+        anything on it AGREEING with the context payload would turn an operator
+        deleting an attachment mid-poll into a held release.
+
+        Raises whatever `get_task_context` raises; the caller holds the release
+        on it (`_context_unreadable`).
+
+        Every path that RETURNS clears the failure marker, including the
+        zero-count skip: the condition the marker records is "the release path
+        could not get what it needed", and a task whose attachments were all
+        deleted no longer needs anything. Leaving the row behind would make a
+        much later, unrelated failure inherit an old clock and page immediately.
+        """
+        if task.context_count <= 0:
+            self._context_answered(task.task_number)
+            return []
+        items = self.alissa.get_task_context(task.ref)
+        self._context_answered(task.task_number)
+        if not items:
+            # Not an error and not a hold: the count is denormalised, so this
+            # is what "the last attachment was deleted since the detail read"
+            # looks like. Worth a line, since it is also what a contextCount
+            # that has drifted looks like.
+            log.debug(
+                "%s: declares %d context attachment(s) but the context read "
+                "returned none — releasing without a context section",
+                task.ref, task.context_count,
+            )
+        return items
+
     def _release(
         self,
         task: Task,
@@ -2104,7 +2354,10 @@ class Orchestrator:
 
         Nothing is created until the TRAILER dedupe answers: the pass-level
         scan is label-scoped and cannot see an unlabeled issue that already
-        carries this task's trailer (see `_trailer_dedupe`).
+        carries this task's trailer (see `_trailer_dedupe`). The context read
+        (O14) comes AFTER it, in the one branch that renders a body: a
+        candidate that turns out to be a duplicate adopts an existing issue and
+        never renders, so it must not spend the read either.
 
         `note` is the caller's missed-trailer warning (empty unless this is a
         SCOPELESS release with trailer-like text in the body). It rides on the
@@ -2112,13 +2365,22 @@ class Orchestrator:
         the record of a task taking the whole lane -- possibly on the strength
         of a trailer nobody parsed. It is passed in rather than recomputed so
         one candidate can never produce two of them; the dedupe path returns
-        above with its own note, computed on the ISSUE body it acts on."""
+        above with its own note, computed on the ISSUE body it acts on. The
+        renderer's own context note (what was rendered, cut or escaped) is
+        appended to it, so one release still produces exactly one line."""
         owner, _, repo = target.partition("/")
         preexisting = self._trailer_dedupe(task, target, occupancy, bow=bow)
         if preexisting is not None:
             return preexisting
 
-        body = render_issue_body(task, target, scope, self.config)
+        try:
+            context = self._read_context(task)
+        except AlissaError as exc:
+            return self._context_unreadable(task, exc)
+
+        rendered = render_issue(task, target, scope, self.config, context)
+        body = rendered.body
+        note += rendered.context_note
 
         if self.config.dry_run:
             occupancy.setdefault(target, []).append(scope)
@@ -2424,7 +2686,7 @@ def _strip_control_lines(text: str, config: Config) -> str:
     `render_issue_body`, so this only removes the operator's raw form."""
     marker_re = re.compile(rf"^{re.escape(config.marker_key)}\s*:", re.IGNORECASE)
     scope_re = re.compile(rf"^{re.escape(config.scope_key)}\s*:", re.IGNORECASE)
-    task_re = re.compile(r"^Alissa-Task\s*:", re.IGNORECASE)
+    task_re = re.compile(rf"^{re.escape(TASK_TRAILER_KEY)}\s*:", re.IGNORECASE)
     kept: list[str] = []
     for line in text.splitlines():
         stripped = line.strip()
@@ -2436,30 +2698,422 @@ def _strip_control_lines(text: str, config: Config) -> str:
     return "\n".join(kept).strip()
 
 
-def render_issue_body(task: Task, target: str, scope: list[str], config: Config) -> str:
+def control_keys(config: Config) -> tuple[str, ...]:
+    """Every trailer key a line in the rendered body must not begin with.
+
+    All THREE of the canonical block's keys, not just the two the marker
+    contract owns. `Alissa-Task` is here because it is parsed exactly like the
+    others -- `ghclient.TASK_TRAILER_RE` is line-anchored and first-match-wins
+    -- and a body remapped to a stranger's task number is the worst of the
+    three outcomes: the close edge would drive that task forward on merge.
+    """
+    return (config.marker_key, config.scope_key, TASK_TRAILER_KEY)
+
+
+@lru_cache(maxsize=None)
+def _control_line_re(keys: tuple[str, ...]) -> re.Pattern[str]:
+    """A line-start match for any of `keys` followed by a colon.
+
+    Deliberately WIDER than the parsers it defends: case-insensitive (the
+    parsers split on this -- `parse_marker` is case-sensitive,
+    `_strip_control_lines` is not) and tolerant of space before the colon
+    (`_strip_control_lines` allows it, `parse_marker` does not). Escaping a
+    line no parser would have read costs one `> ` in an issue body; missing one
+    a parser WOULD have read costs a retargeted release.
+    """
+    alternation = "|".join(re.escape(key) for key in keys)
+    return re.compile(rf"^(?:{alternation})[ \t]*:", re.IGNORECASE)
+
+
+def escape_control_lines(text: str, keys: tuple[str, ...]) -> tuple[str, int]:
+    """`(text, n)` with every line that begins with one of `keys` blockquoted.
+
+    Split on `"\\n"` and nothing else: that is exactly the set of line starts
+    `re.MULTILINE`'s `^` recognises, and `str.splitlines()` is not -- it also
+    breaks on `\\v`, `\\f`, `\\x1c`-`\\x1e` and `\\u2028`/`\\u2029`, so it would
+    report a "line" the parsers cannot see and, worse, JOIN back on `\\n` and
+    thereby CREATE one. The escape must not be able to manufacture the
+    condition it exists to remove.
+
+    Blockquoting (`> `) rather than a backslash escape: `\\A` is not a
+    CommonMark escape (only ASCII punctuation is), so it would render as a
+    literal backslash, while a blockquote renders as quoted text and reads as
+    what it is. The prefix is applied even inside a fenced code block -- a
+    fence means nothing to a line-anchored regex, so a code block is exactly
+    where an injected trailer would hide.
+    """
+    pattern = _control_line_re(keys)
+    escaped = 0
+    out: list[str] = []
+    for line in text.split("\n"):
+        if pattern.match(line):
+            line = CONTEXT_ESCAPE_PREFIX + line
+            escaped += 1
+        out.append(line)
+    return "\n".join(out), escaped
+
+
+def count_escaped_lines(text: str, keys: tuple[str, ...]) -> int:
+    """How many lines of `text` are escaped control lines.
+
+    Counted on RENDERED text rather than accumulated as blocks are built, so
+    the number describes the body on every path -- including the partial cut,
+    which truncates a block after it was escaped and would otherwise report
+    escapes that were cut away with the tail.
+
+    The one over-count: an attachment whose own write-up literally contains
+    `> Autonomous-Dev: ...` is indistinguishable from a line this renderer
+    escaped, and is counted. That line is trailer-like text sitting inert in an
+    issue body either way, so naming it in the log is not misleading.
+    """
+    pattern = _control_line_re(keys)
+    return sum(
+        1
+        for line in text.split("\n")
+        if line.startswith(CONTEXT_ESCAPE_PREFIX)
+        and pattern.match(line[len(CONTEXT_ESCAPE_PREFIX):])
+    )
+
+
+def strip_context_section(body: str, config: Config) -> str:
+    """An ISSUE body with the rendered `## Context` section removed.
+
+    For the O13 missed-trailer warning only, and only on issue bodies. That
+    warning means "a human wrote a trailer where the parser cannot see it", and
+    after O14 an issue body contains text no human wrote: every escaped context
+    line (`> Autonomous-Scope: ...`) is, by construction, a key that is not at a
+    line start -- exactly what `find_mid_line_trailer` reports. Left alone, a
+    scopeless release whose attachments merely MENTIONED a trailer warns every
+    poll, for the life of the issue, pointing the operator at a task body with
+    nothing in it to fix.
+
+    Delimited excision rather than "skip lines starting with the escape
+    prefix": a human who hand-writes `> Autonomous-Scope: src/**` into an issue
+    HAS written a trailer the parser cannot see, and silencing that is exactly
+    the signal O13 exists to give. This removes only what orcloop itself
+    generated, and a body whose section a human edited away has nothing to
+    remove.
+
+    THE START ANCHOR. `## Context` is not orcloop's to claim on the way IN any
+    more than `## ` was on the way out: a task description is operator markdown
+    and "Context" is one of the headings an operator most likely writes (this
+    repo's README has one). So the section is the LAST `## Context` before the
+    first terminator that is also STRUCTURALLY one -- first non-blank line
+    under it is a `### ` subsection or the truncation notice, which is what
+    `render_context_section` emits in all three of its shapes. The `last` is
+    what picks orcloop's over an operator's when a body has both; the
+    structural test is what stops a ZERO-attachment body (no section rendered
+    at all -- every task predating O14) from having the operator's own heading
+    excised instead.
+
+    The rule behind both: **when the anchor is ambiguous, do nothing.** Not
+    excising costs a spurious warning an operator can dismiss; excising wrongly
+    costs a warning they never see, and a lost diagnostic is the failure this
+    function's own callers exist to prevent. Every tie breaks toward keeping
+    the signal. Residual: an operator heading `## Context` followed by their own
+    `### ` subheading on a task with no attachments.
+
+    THE TERMINATORS, and why there are two. A bare `## ` test is wrong: an
+    attachment is operator markdown and operator markdown has headings, so the
+    first heading in a write-up would end the excision and hand every escaped
+    line after it back to the warning (PR #35 review, round 2).
+
+    * **A line that begins with a control key** -- the canonical trailer block.
+      Attachment content CANNOT spell this one, and the guarantee comes from
+      the escape itself: `escape_control_lines` leaves no line inside the
+      section beginning with a control key, so a line-start `Autonomous-Dev:`
+      can only be the block `render_issue` emitted. The property added for
+      injection doubles as an unspoofable delimiter, which is why no sentinel
+      markup is needed in the body.
+    * **`DOD_HEADING` / `CRITERIA_HEADING`** -- needed because the trailer
+      terminator alone would swallow those two sections, and they are
+      human-written text where O13 should still warn. These ARE spellable by an
+      attachment; the residual is that a write-up reproducing one of the two
+      verbatim ends the excision early and the warning returns for that issue.
+      The cost is log noise: this function feeds only `_malformed_trailer`, and
+      both call sites still take `parse_scope` from the RAW body, so no lane,
+      dedupe or trailer parse can be moved by anything here.
+    """
+    terminator = _control_line_re(control_keys(config))
+    lines = body.split("\n")
+
+    def ends_the_section(index: int) -> bool:
+        line = lines[index]
+        return (
+            line.strip() in (DOD_HEADING, CRITERIA_HEADING) or bool(terminator.match(line))
+        )
+
+    def renders_a_section(index: int) -> bool:
+        """Whether the `## Context` at `index` is followed by what this
+        renderer puts under one: a `### ` subsection (the normal and
+        partial-cut shapes) or the truncation notice (the nothing-fit shape)."""
+        for line in lines[index + 1:]:
+            if not line.strip():
+                continue
+            return line.startswith(CONTEXT_SUBHEADING) or line.startswith(
+                CONTEXT_TRUNCATED_PREFIX
+            )
+        return False
+
+    start = -1
+    for index in range(len(lines)):
+        if ends_the_section(index):
+            break
+        if lines[index].strip() == CONTEXT_HEADING and renders_a_section(index):
+            start = index  # LAST valid candidate wins: see below
+    if start < 0:
+        return body
+
+    end = len(lines)
+    for index in range(start + 1, len(lines)):
+        if ends_the_section(index):
+            end = index
+            break
+    return "\n".join(lines[:start] + lines[end:])
+
+
+def _context_item_block(item: ContextItem, cap: int) -> tuple[str, bool]:
+    """One attachment as `(markdown, was_truncated)`, before escaping.
+
+    Title, then the `note` (the operator's one-line "why this is relevant") in
+    italics, then the payload: the markdown write-up AND the link. Both, not
+    the first one present -- `markdownContent` and `link` are independent fields
+    and an attachment may carry both, so picking one would silently discard
+    operator content, which is the failure mode this whole feature exists to
+    remove. The link is rendered bare (GitHub autolinks it; angle brackets would
+    break on a `>` inside the URL) and is never truncated: a URL is bounded by
+    nature and it is the pointer back to the full source when the write-up was
+    cut. An attachment whose payload this adapter does not inline (a vault
+    reference) still gets its titled subsection -- the title and the note are
+    themselves the decision often enough.
+
+    Only the write-up is capped, at `cap`. `cap` is the per-attachment ceiling
+    the caller can afford, which is `CONTEXT_ITEM_MAX_CHARS` unless the section
+    budget is tighter than that.
+    """
+    lines = [f"{CONTEXT_SUBHEADING}{item.title.strip() or CONTEXT_UNTITLED}", ""]
+    if item.note.strip():
+        lines.extend([f"_{item.note.strip()}_", ""])
+
+    content = item.markdown.strip()
+    # Captured BEFORE the reassignment below: recomputing it from `item` would
+    # keep reporting the right number only for as long as `content` is derived
+    # exactly one way, and the marker's job is to describe what was actually cut.
+    original = len(content)
+    truncated = original > cap
+    if truncated:
+        content = (
+            content[:cap].rstrip()
+            + f"\n\n{CONTEXT_TRUNCATED_PREFIX} {cap} of {original} chars]"
+        )
+    link = item.link.strip()
+    if link:
+        content = f"{content}\n\n{link}" if content else link
+    lines.append(content or CONTEXT_EMPTY)
+    return "\n".join(lines), truncated
+
+
+def _omitted_notice(rendered: int, total: int, budget: int) -> str:
+    return (
+        f"{CONTEXT_TRUNCATED_PREFIX} {rendered} of {total} attachments "
+        f"rendered; the section is capped at {budget} chars]"
+    )
+
+
+def render_context_section(
+    items: Sequence[ContextItem], config: Config, budget: int
+) -> tuple[str, str]:
+    """`(section_markdown, note)` for the origin task's context attachments.
+
+    `note` is a one-line summary for the release log -- empty only when there
+    was nothing to render. Nothing here is silent: every attachment that was
+    cut, dropped or escaped is counted into it AND marked in the body.
+
+    ORDER is chronological on `created_at`, sorted stably, so a payload with no
+    timestamps at all (a shape this adapter must not assume away) keeps the
+    endpoint's own order, which is creation order.
+
+    `budget` is the hard character ceiling for everything returned, computed by
+    the caller from what is LEFT under GitHub's issue-body limit -- see
+    `render_issue`. Fitting is by whole attachment: a half-rendered decision
+    reads as a whole one, whereas "2 of 5 rendered" sends the operator to the
+    task. Per-attachment truncation (`CONTEXT_ITEM_MAX_CHARS`) is the one place
+    a single attachment is cut, and it says so where it was cut.
+    """
+    if not items:
+        return "", ""
+
+    keys = control_keys(config)
+    blocks: list[tuple[str, bool]] = []
+    for item in sorted(items, key=lambda entry: entry.created_at):
+        block, truncated = _context_item_block(item, CONTEXT_ITEM_MAX_CHARS)
+        block, _ = escape_control_lines(block, keys)
+        blocks.append((block, truncated))
+
+    total = len(blocks)
+    sep = "\n\n"
+    # An upper bound on the notice: its two counts are both <= `total`, and the
+    # limit it finally reports is <= `budget`, so rendering it with `total`
+    # twice and `budget` can only be at least as wide as the one emitted.
+    reserve = len(sep) + len(_omitted_notice(total, total, budget))
+    if len(CONTEXT_HEADING) + reserve > budget:
+        # No room even to SAY that nothing fit. Reachable only when the rest of
+        # the body has all but exhausted GitHub's limit on its own; the issue
+        # still gets filed, so this line is the only record.
+        log.error(
+            "context section dropped entirely: %d attachment(s) did not fit in "
+            "the %d chars left under GitHub's %d-char issue-body limit — the "
+            "issue is filed WITHOUT them; shorten the task description or the "
+            "definition of done",
+            total, budget, GITHUB_BODY_LIMIT,
+        )
+        return "", f"; NOTE: {total} context attachment(s) dropped — no room under the body limit"
+
+    def fit(limit: int) -> int:
+        used = len(CONTEXT_HEADING)
+        count = 0
+        for block, _ in blocks:
+            cost = len(sep) + len(block)
+            if used + cost > limit:
+                break
+            used += cost
+            count += 1
+        return count
+
+    kept = fit(budget)
+    limit = budget
+    if kept < total:
+        # Something is being omitted, so the notice is going to be emitted and
+        # has to be paid for. Re-fit against the smaller ceiling -- and REPORT
+        # that ceiling, since it is the one that was applied.
+        limit = budget - reserve
+        kept = fit(limit)
+
+    rendered = [block for block, _ in blocks[:kept]]
+    partial = ""
+    if kept == 0 and total:
+        # Nothing fits whole, but there is room to say something. Rendering the
+        # first decision beats rendering none, and the per-attachment cap
+        # already establishes that a marked partial is an acceptable shape --
+        # so the whole-attachment rule yields exactly here, at the point where
+        # keeping it would mean an empty section. Cutting the ESCAPED block from
+        # the end is safe: truncation only removes text, so it cannot produce a
+        # line start the escape has not already seen.
+        room = limit - len(CONTEXT_HEADING) - len(sep) - len(CONTEXT_PARTIAL_MARKER)
+        if room >= CONTEXT_MIN_PARTIAL_CHARS:
+            partial = blocks[0][0][:room].rstrip() + CONTEXT_PARTIAL_MARKER
+            rendered = [partial]
+
+    parts = [CONTEXT_HEADING] + rendered
+    if kept < total:
+        parts.append(_omitted_notice(kept, total, limit))
+    section = sep.join(parts)
+
+    # What actually REACHED the body, which on the partial path is not
+    # `blocks[:kept]` -- that branch renders `blocks[0]` while deliberately
+    # leaving `kept` at 0 for the notice's sake. Counting the slice alone made
+    # the one attachment in the body the one attachment neither counter could
+    # see, which is precisely what this function's docstring promises cannot
+    # happen. `kept` keeps its meaning; only the counters widen.
+    counted = blocks[:1] if partial else blocks[:kept]
+    truncations = sum(1 for _, truncated in counted if truncated)
+    escapes = count_escaped_lines(section, keys)
+    summary = f"{kept} of {total}" if kept < total else str(total)
+    note = f"; context: {summary} attachment(s) rendered"
+    if partial:
+        note += ", 1 rendered partially to fit"
+    if truncations:
+        note += f", {truncations} truncated"
+    if escapes:
+        note += f", {escapes} trailer-like line(s) escaped"
+    return section, note
+
+
+@dataclass(frozen=True)
+class RenderedIssue:
+    """The issue body plus what rendering it had to say out loud."""
+
+    body: str
+    # The `; context: ...` suffix for the release line -- empty when the task
+    # had no context attachments (the common case, and the only one that
+    # renders byte-identically to pre-O14).
+    context_note: str = ""
+
+
+def render_issue(
+    task: Task,
+    target: str,
+    scope: list[str],
+    config: Config,
+    context: Sequence[ContextItem] = (),
+) -> RenderedIssue:
     """The mechanical issue body: task description (control trailers stripped)
-    + Definition of Done + acceptance-criteria checklist + a canonical trailer
-    block. The `Autonomous-*` trailers are re-emitted (line-anchored, git-trailer
-    style) so lane occupancy stays derivable from the open issues, and the
-    `Alissa-Task:` trailer links the issue back to its origin task for the
-    develop daemon and the close loop."""
+    + the origin task's context attachments + Definition of Done +
+    acceptance-criteria checklist + a canonical trailer block. The
+    `Autonomous-*` trailers are re-emitted (line-anchored, git-trailer style) so
+    lane occupancy stays derivable from the open issues, and the `Alissa-Task:`
+    trailer links the issue back to its origin task for the develop daemon and
+    the close loop.
+
+    `context` (O14, issue #34) is a SNAPSHOT taken at release time: the section
+    sits after the description and before the Definition of Done, because it is
+    the operator amending the brief, not adding a requirement. With no
+    attachments -- the common case, and every case before O14 -- the body is
+    byte-identical to what shipped through 0.3.7 (the last release before this
+    section existed).
+
+    The context section's ceiling is what is LEFT under GitHub's issue-body
+    limit after everything else, capped further at `CONTEXT_SECTION_MAX_CHARS`.
+    It yields to the rest of the body rather than the other way around: the
+    description, the DoD and the criteria come from the operator's own task and
+    are the issue's contract, while the context is the part orcloop is adding.
+    """
     sections: list[str] = []
 
     prose = _strip_control_lines(task.description, config)
     if prose:
         sections.append(prose)
+    # Where the context section goes: straight after the description, or first
+    # when there is none.
+    context_at = len(sections)
 
     if task.definition_of_done.strip():
-        sections.append("## Definition of Done\n\n" + task.definition_of_done.strip())
+        sections.append(DOD_HEADING + "\n\n" + task.definition_of_done.strip())
 
     if task.criteria:
         checklist = "\n".join(f"- [ ] {c.description}" for c in task.criteria)
-        sections.append("## Acceptance criteria\n\n" + checklist)
+        sections.append(CRITERIA_HEADING + "\n\n" + checklist)
 
     trailers = [f"{config.marker_key}: {target}"]
     if scope:
         trailers.append(f"{config.scope_key}: {', '.join(scope)}")
-    trailers.append(f"Alissa-Task: {task.ref}")
+    trailers.append(f"{TASK_TRAILER_KEY}: {task.ref}")
     sections.append("\n".join(trailers))
 
-    return "\n\n".join(sections) + "\n"
+    body = "\n\n".join(sections) + "\n"
+    if not context:
+        return RenderedIssue(body)
+
+    section, note = render_context_section(
+        context,
+        config,
+        # `body` already accounts for the trailing newline; the section costs
+        # itself plus the "\n\n" that joins it in.
+        min(CONTEXT_SECTION_MAX_CHARS, GITHUB_BODY_LIMIT - len(body) - 2),
+    )
+    if not section:
+        return RenderedIssue(body, note)
+    sections.insert(context_at, section)
+    return RenderedIssue("\n\n".join(sections) + "\n", note)
+
+
+def render_issue_body(
+    task: Task,
+    target: str,
+    scope: list[str],
+    config: Config,
+    context: Sequence[ContextItem] = (),
+) -> str:
+    """`render_issue(...).body` -- the body alone, for callers with nothing to
+    report about how it was rendered."""
+    return render_issue(task, target, scope, config, context).body

{alissa_tools_github_orcloop-0.3.7 → alissa_tools_github_orcloop-0.3.8}/src/main/alissa/tools/github/orcloop/state.py

@@ -67,12 +67,16 @@ CREATE TABLE IF NOT EXISTS meta (
 """
 
 
-# The only `escalations` kinds `clear_escalation` will remove: the O9 dedupe
-# outage clock and the page it raises, both of which describe a condition that
-# can END (see `clear_escalation`). Spelled as literals here rather than
-# imported from `loop`, which imports this module; `test_loop` pins that the
-# loop's constants and this set stay the same two strings.
-CLEARABLE_KINDS = frozenset({"marker:dedupe-unreadable", "dedupe-unreadable"})
+# The only `escalations` kinds `clear_escalation` will remove: two outage clocks
+# and the two pages they raise -- the O9 dedupe check and the O14 context read --
+# all four of which describe a condition that can END (see `clear_escalation`).
+# Spelled as literals here rather than imported from `loop`, which imports this
+# module; `test_loop` pins that the loop's constants and this set stay the same
+# four strings.
+CLEARABLE_KINDS = frozenset({
+    "marker:dedupe-unreadable", "dedupe-unreadable",
+    "marker:context-unreadable", "context-unreadable",
+})
 
 
 class State:

alissa_tools_github_orcloop-0.3.8/src/main/alissa/tools/github/orcloop/version

@@ -0,0 +1 @@
+0.3.8

{alissa_tools_github_orcloop-0.3.7 → alissa_tools_github_orcloop-0.3.8/src/main/alissa_tools_github_orcloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.3.7
+Version: 0.3.8
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_orcloop-0.3.7/src/main/alissa/tools/github/orcloop/version

@@ -1 +0,0 @@
-0.3.7