alissa-tools-github-genloop 0.1.0__py3-none-any.whl

alissa/tools/github/genloop/loop_events.py

@@ -0,0 +1,115 @@
+"""Loop-events push: the seat's decisions as idempotent telemetry, one
+best-effort batch per poll (Studio `POST /v1/loop-events`).
+
+The shape is orcloop's (`loop_events.py` there): `seat`, a dotted `kind`, `at`
+in epoch MILLISECONDS, and a `dedupeKey` the server is idempotent on -- so a
+resend is a silent duplicate and this module keeps no retry queue. A fact
+still true next poll is re-recorded under the same key; a failed POST costs at
+most the events of one poll, which the design accepts for telemetry.
+
+`seat: "genloop"` and the six kinds below are D14's (Studio G3-2 added the
+literal to the `loopEvents` union).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Mapping
+
+from .alissa_client import AlissaClient, AlissaError
+
+log = logging.getLogger(__name__)
+
+SEAT = "genloop"
+
+KIND_PLAN_PROPOSED = "plan.proposed"
+KIND_PLAN_SKIPPED = "plan.skipped"
+KIND_PLAN_INVALID = "plan.invalid"
+KIND_PASS_IDLE = "pass.idle"
+KIND_PASS_SILENT = "pass.silent"
+KIND_PASS_STALLED = "pass.stalled"
+KINDS = (
+    KIND_PLAN_PROPOSED, KIND_PLAN_SKIPPED, KIND_PLAN_INVALID,
+    KIND_PASS_IDLE, KIND_PASS_SILENT, KIND_PASS_STALLED,
+)
+
+EVENT_BATCH_MAX = 200
+EVENT_REASON_MAX_CHARS = 2000
+EVENT_REASON_TRUNCATED = " [reason truncated]"
+_KIND_RE = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$")
+
+
+def event(
+    kind: str,
+    *,
+    at: float,
+    dedupe_key: str,
+    repo: str | None = None,
+    pr_number: int | None = None,
+    session: str | None = None,
+    reason: str | None = None,
+    data: Mapping[str, object] | None = None,
+) -> dict:
+    """One event in the ingest contract's shape. `at` is epoch SECONDS here
+    (the seat's clock) and milliseconds on the wire."""
+    if not _KIND_RE.match(kind):
+        raise ValueError(f"kind {kind!r} does not match the server's grammar")
+    out: dict = {"seat": SEAT, "kind": kind, "at": int(at * 1000), "dedupeKey": f"{SEAT}:{dedupe_key}"[:256]}
+    if repo:
+        out["repo"] = repo
+    if pr_number is not None:
+        out["prNumber"] = int(pr_number)
+    if session:
+        out["session"] = session
+    if reason:
+        if len(reason) > EVENT_REASON_MAX_CHARS:
+            reason = reason[:EVENT_REASON_MAX_CHARS - len(EVENT_REASON_TRUNCATED)] + EVENT_REASON_TRUNCATED
+        out["reason"] = reason
+    if data:
+        out["data"] = dict(data)
+    return out
+
+
+class LoopEventRecorder:
+    """The poll's buffer. `record` is called where a fact is observed;
+    `flush` POSTs the batch once per poll and never raises."""
+
+    def __init__(self, alissa: AlissaClient, *, dry_run: bool = False):
+        self.alissa = alissa
+        self.dry_run = dry_run
+        self._buffer: list[dict] = []
+        self._keys: set[str] = set()
+
+    def record(self, kind: str, **fields: object) -> dict:
+        built = event(kind, **fields)  # type: ignore[arg-type]
+        if built["dedupeKey"] not in self._keys:
+            self._keys.add(built["dedupeKey"])
+            self._buffer.append(built)
+        return built
+
+    @property
+    def pending(self) -> list[dict]:
+        return list(self._buffer)
+
+    def flush(self) -> int:
+        """Send what the poll recorded; returns how many were sent. A
+        failure is a WARNING and the buffer is dropped (the keys make a
+        re-observed fact safe to resend)."""
+        batch, self._buffer, self._keys = self._buffer, [], set()
+        if not batch:
+            return 0
+        if self.dry_run:
+            for item in batch:
+                log.info("[dry-run] would emit %s (%s)", item["kind"], item["dedupeKey"])
+            return 0
+        sent = 0
+        for start in range(0, len(batch), EVENT_BATCH_MAX):
+            chunk = batch[start:start + EVENT_BATCH_MAX]
+            try:
+                self.alissa.post_loop_events(chunk)
+            except AlissaError as exc:
+                log.warning("loop events: push of %d event(s) failed (%s)", len(chunk), exc)
+                continue
+            sent += len(chunk)
+        return sent

alissa/tools/github/genloop/pass_directive.py

@@ -0,0 +1,325 @@
+"""The pass: the directive one `genloop-<stamp>` session works under, and the
+record it leaves for the seat (design D14, §3, §4.1, §5.2, §5.5).
+
+The issue names this module `pass.py`; `pass` is a Python keyword, so a module
+of that name cannot be imported with an import statement. It is
+`pass_directive.py` here, with the same content.
+
+BYTE-PINNED
+===========
+`GEN_DIRECTIVE` is the whole contract the session works under, in one string.
+`test_pass_directive` pins its SHA-256 and every sentence a guarantee rests
+on: the skill and its fail-closed record, the direction reads of §4.1, the
+sources of §3 in rank order, the files of §5.2 quoted, `plan-lint` as the
+last step before the push, the record schema, and what the session may NOT do
+-- open the PR, request the reviewer, create tasks, kill other sessions. The
+seat does those. Changing one byte of the template is a deliberate edit to
+the pin, never a drift.
+
+The judgment is the session's; the seat never reads the plan's prose.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+from typing import Sequence
+
+SESSION_PREFIX = "genloop-"
+SESSION_TMUX_PREFIX = "ali-" + SESSION_PREFIX
+STAMP_FORMAT = "%Y%m%dT%H%M%SZ"
+PASSES_DIRNAME = "passes"
+
+RECORD_VERSION = 1
+VERDICT_PLAN = "plan"
+VERDICT_IDLE = "idle"
+VERDICT_SKILL_MISSING = "skill-missing"
+VERDICTS = (VERDICT_PLAN, VERDICT_IDLE, VERDICT_SKILL_MISSING)
+
+PASS_RECORD_SCHEMA = (
+    '{"version": 1, "stamp": "<this pass\'s stamp>", '
+    '"verdict": "plan" | "idle" | "skill-missing", '
+    '"branch": "PLAN-<stamp>-<slug>" (verdict plan only), '
+    '"planId": "<yyyy-mm-dd>-<slug>" (verdict plan only), '
+    '"skipped": [{"key": "<source key, candidate or check>", "reason": '
+    '"budget" | "parked" | "rule" | "dedupe" | "unanchored" | "lint" | "bound" | "<one word>"}], '
+    '"amended": [<number of each open plan PR you amended and pushed>]}'
+)
+
+GEN_DIRECTIVE = (
+    "You are the GENLOOP pass for the loopwork fleet, spawned by the genloop seat as managed "
+    "session `{session}` (pass stamp `{stamp}`, UTC day `{day}`). You are the fleet's judgment "
+    "seat: you read the operator's direction and the loop's exhaust and write AT MOST ONE plan "
+    "as files on a branch. The seat — not you — opens the pull request, requests the reviewer, "
+    "records the plan and delivers.\n"
+    "\n"
+    "Fixed facts for this pass:\n"
+    "- Plans repository: `{plans_repo}`. Its worktree hub (the one checkout in this container) "
+    "is `{plans_hub}`.\n"
+    "- Fed repositories (read them with `gh api` / `gh search` only — never clone): {repos}.\n"
+    "- Exhaust window: the last {window_days} days.\n"
+    "- Alissa: `$ALISSA_BASE` with `Authorization: Bearer $ALISSA_API_TOKEN` (the planner's own "
+    "token — reads only, see step 9).\n"
+    "- Budget: {budget_note}\n"
+    "- Your pass record: `{record_path}`.\n"
+    "\n"
+    "1. Load the skill `{skill}`. If it cannot be loaded, do NOT improvise the pass: write "
+    '`{record_path}` containing exactly {{"version": 1, "stamp": "{stamp}", "verdict": '
+    '"skill-missing", "skipped": [], "amended": []}} and go to step 10 (fail closed).\n'
+    "2. Read the direction, in this order (design §4.1): (a) `GET /v1/factory/steering` — the "
+    "fleet row first: if `parked` is true, write the record with verdict `idle` and skipped "
+    '[{{"key": "fleet", "reason": "parked"}}] and go to step 10; else its `priorities[]`, '
+    "`offLimits[]`, `notNow[]`; (b) the active programs: `GET /v1/projects?includeShared=true` "
+    "filtered to `status: \"active\"`, then `GET /v1/projects/:projectId` each — the outcome, "
+    "the milestones with their status and their open validation criteria (`satisfied: false`), "
+    "the observability block; a milestone `at_risk` or `missed` ranks its program first; (c) each "
+    "program's steering row (scope `program`): `budgetShare`, `offLimits[]`, `notNow[]`; (d) the "
+    "program's objectives, `GET /v1/objectives/:objectiveId`; (e) strategies whose actions name "
+    "a program, where any exist — say so when none do; (f) the proposal rules, `GET "
+    "/v1/factory/proposal-rules`, which remove candidates and never add direction.\n"
+    "3. Budget per candidate program: `GET /v1/code/budget?scope=program&projectId=<id>&window=30d`. "
+    "`exhausted`, or `spentUsd >= budgetShare x capUsd` when the program row sets a "
+    "`budgetShare`, or a read that fails: plan nothing for that program (skipped, reason "
+    "`budget`). `warn`: you may plan, and the plan's *Why now* states the remaining figure.\n"
+    "4. Derive the spent-set (D6) before choosing: a source key is SPENT when a plan that lists "
+    "it is open or committed (`GET /v1/loop/plans?status=proposed`, `…=parked`, "
+    "`…=committed`), when a proposal rule names it or a prefix of it, or when an open issue or "
+    "task already carries `Alissa-Source: <key>` (`gh search issues` over the fed repositories, "
+    "`gh issue list --state all --search`). Never propose a spent key; list it under `skipped` "
+    "with reason `dedupe` or `rule`.\n"
+    "5. Open plans first (D13). For every OPEN pull request in `{plans_repo}` on a `PLAN-` "
+    "branch by your GitHub login: when its `plan-lint` check run concluded `failure`, or a "
+    "`[blocker]` / `[major]` / `[minor]` / `[question]` finding on it has no `[triage:*]` "
+    "answer, answer EACH finding with exactly one `[triage:pursue]`, `[triage:ignore]` or "
+    "`[triage:later]` reply on its own thread FIRST, then amend the files in a worktree of "
+    "that branch, run step 7's lint, and push the branch. Replies before the push, always "
+    "(L14). Add the PR's number to `amended`; never request the review yourself — the seat "
+    "re-requests it.\n"
+    "6. Walk the sources in rank order (design §3) over the fed repositories and the window; "
+    "stop at the first plan worth proposing. The parse is a rule, never a reading:\n"
+    "   1. Unverified operator's-gate items — `GET /v1/loop-events?kind=close.merged` "
+    "(`data.deliveryNotesPresent: true`), then the merged PR body's `## Delivery notes`, the "
+    "bullets under **Not verified — operator's gate** → `gate-verification`; key "
+    "`gate:<repo>#<pr>:<hash8>` (the first 8 hex of the bullet's SHA-256).\n"
+    "   2. `[triage:later]` replies on those merged PRs whose cited task is `draft` or absent "
+    "→ `exhaust-followup`; key `later:<repo>#<pr>:<commentId>`.\n"
+    "   3. Reviewer `[minor]` / `[nit]` findings on the approving round with no "
+    "`[triage:pursue]` reply, folded per PR → `exhaust-followup`; key "
+    "`minor:<repo>#<pr>:<commentId>`.\n"
+    "   4. Recurring escalations and cap-outs over 14 days (`GET /v1/loop-events?seat=…&kind=…`): "
+    "one `(repo, kind)` on >= 3 items, or one item capped twice → `flaky-test` or `drift-fix` "
+    "on the mechanism; key `esc:<repo>:<kind>:<n>` or `esc:<repo>:<kind>:*`.\n"
+    "   5. Drift — one `gh api …/contents/<path>` read per contract file: the loop labels, the "
+    "readiness class enums, the loop-event vocabulary, the session-name grammar, each leaf "
+    "Dockerfile's `FROM` tag against `alissa-loopwork`'s `VERSION` → `drift-fix` on the "
+    "lagging repo; key `drift:<contract>:<value>`.\n"
+    "   6. Stale abandoned tasks — NEVER a plan; list them under `skipped` with reason `stale` "
+    "and key `stale:TASK-<n>` for the digest.\n"
+    "   Only merged work is exhaust. A plan folds keys of ONE class, never several classes.\n"
+    "   Anchoring (§4.3): every plan cites one anchor — a milestone (every task in that "
+    "milestone's body of work), an unsatisfied criterion (*Why now* says what satisfies it), "
+    "an active objective (through a program's milestone), or an exhaust class (non-empty "
+    "`sources`, every key of that class). Nothing in `offLimits[]` or `notNow[]` is planned. A "
+    "plan you cannot anchor is not written (skipped, reason `unanchored`).\n"
+    "7. To write the plan: `git -C {plans_hub} fetch origin`, then from `{plans_hub}` run `git "
+    "worktree add -b PLAN-{stamp}-<slug> PLAN-{stamp}-<slug> origin/<default branch>` and work "
+    "ONLY in that worktree. Create exactly one new directory `plans/{day}-<slug>/` (slug "
+    "`[a-z0-9-]{{3,48}}`) holding `plan.md` and 1–8 files `tasks/<id>.md`, and nothing else — "
+    "never `materialized.json`, never a file outside the directory. The files (design §5.2), "
+    "verbatim in shape:\n"
+    "\n"
+    "{plan_skeleton}\n"
+    "\n"
+    "{task_skeleton}\n"
+    "\n"
+    "   Every task carries full task data, never a headline (D15): in a task file everything "
+    "above `## Definition of done` is the description (400–8,000 characters), *Definition of "
+    "done* is the definition, each item under *Criteria* one criterion. Then lint — the LAST "
+    "step before the push: in the worktree run `npm ci` (once), `npm run plan-lint -- --write "
+    "plans/{day}-<slug>` (it renders *Summary* and *Dependency graph*), then `npm run plan-lint "
+    "-- plans/{day}-<slug>`. Push only when that last run exits 0: commit, then `git push -u "
+    "origin PLAN-{stamp}-<slug>`. A plan the lint refuses and you cannot fix is never pushed "
+    "(skipped, reason `lint`).\n"
+    "8. Write `{record_path}` — always, even when you write no plan. It MUST follow this "
+    "schema (verdict `plan` only when you pushed a branch this pass; `idle` otherwise):\n"
+    "{schema}\n"
+    "9. NEVER open a pull request, NEVER request a reviewer, NEVER create or edit a task, a "
+    "project or any other Alissa record (no POST, PUT or DELETE to Alissa at all), NEVER add a "
+    "label, merge, close or comment beyond step 5's triage replies, NEVER push to any branch "
+    "that is not a `PLAN-` branch, NEVER clone a fed repository, and NEVER kill any session "
+    "but your own. The seat opens the PR, requests the reviewer and records the plan; your "
+    "output is the branch and the record.\n"
+    "10. Your LAST act, after the record is written: run `alissa tmux kill {session}` to end "
+    "this session and free the machine.\n"
+)
+
+# Design §5.2, quoted.
+PLAN_SKELETON = """\
+`plan.md`:
+---
+id: <yyyy-mm-dd>-<slug>
+title: <title>
+anchor: { kind: <milestone|criterion|objective|exhaust>, … }
+program: <projectId>
+milestone: <bodyOfWorkId>                # absent only on an exhaust anchor (§10 Q3)
+sources:
+  - { key: <source key>, evidence: <one line> }
+budget: { estimateUsd: <n>, basis: <one line> }
+supersedes: plans/<dir>                  # when one
+---
+# Plan: <title>
+<!-- alissa-genloop:plan v1 -->
+
+## Why now
+## What it serves
+## Summary
+<!-- plan-summary:begin -->
+- `<id>` — <task title> (<repo>, <commitClass>)
+<!-- plan-summary:end -->
+## Dependency graph
+<!-- plan-dag:begin -->
+```mermaid
+graph LR
+  <id> -->|hard| <id>
+```
+<!-- plan-dag:end -->
+## Considered and skipped
+## Open questions for the reviewer"""
+
+TASK_SKELETON = """\
+`tasks/<id>.md`:
+---
+id: <slug>
+title: <title>
+repo: <owner>/<repo>
+milestone: <bodyOfWorkId>
+priority: <low|medium|high|top>
+dependsOn:
+  - { id: <slug>, type: <hard|soft> }
+  - { task: TASK-<n>, type: <hard|soft> }
+scope:
+  - <glob>
+commitClass: <one of §7.1, never unanchored>
+sources:
+  - <source key>
+---
+## Why
+## Definition of done
+## Criteria
+- <criterion>"""
+
+# The pin: the template, the two quoted skeletons and the schema, hashed
+# together. `test_pass_directive` asserts this value; the seat logs it with
+# every spawn so a pass can be traced to the exact contract it ran under.
+DIRECTIVE_SHA256 = hashlib.sha256(
+    "\x00".join((GEN_DIRECTIVE, PLAN_SKELETON, TASK_SKELETON, PASS_RECORD_SCHEMA)).encode("utf-8")
+).hexdigest()
+
+
+def session_name(stamp: str) -> str:
+    return SESSION_PREFIX + stamp
+
+
+def render_directive(
+    *,
+    stamp: str,
+    day: str,
+    skill: str,
+    plans_repo: str,
+    plans_hub: str,
+    repos: Sequence[str],
+    window_days: int,
+    record_path: str,
+    budget_note: str,
+) -> str:
+    """The directive for the pass stamped `stamp`. Pure -- the tests pin it
+    without a filesystem."""
+    return GEN_DIRECTIVE.format(
+        session=session_name(stamp),
+        stamp=stamp,
+        day=day,
+        skill=skill,
+        plans_repo=plans_repo,
+        plans_hub=plans_hub,
+        repos=", ".join(f"`{r}`" for r in repos) if repos else "(none — write the record with verdict idle)",
+        window_days=window_days,
+        record_path=record_path,
+        budget_note=budget_note,
+        plan_skeleton=PLAN_SKELETON,
+        task_skeleton=TASK_SKELETON,
+        schema=PASS_RECORD_SCHEMA,
+    )
+
+
+# --- the record ----------------------------------------------------------------
+
+
+class PassRecordError(ValueError):
+    """The record does not follow the schema the directive carries."""
+
+
+@dataclass(frozen=True)
+class Skip:
+    key: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class PassRecord:
+    stamp: str
+    verdict: str
+    branch: str | None
+    plan_id: str | None
+    skipped: tuple[Skip, ...]
+    amended: tuple[int, ...]
+
+
+_BRANCH_RE = re.compile(r"^PLAN-(\d{8}T\d{6}Z)-([a-z0-9-]+)$")
+_PLAN_ID_RE = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9][a-z0-9-]{2,47}$")
+_REASON_RE = re.compile(r"^[a-z][a-z0-9_-]{0,31}$")
+
+
+def parse_pass_record(payload: object, *, stamp: str) -> PassRecord:
+    """Parse one `passes/<stamp>.json` against the schema; raises
+    `PassRecordError` naming the first violation."""
+    if not isinstance(payload, dict):
+        raise PassRecordError("the record is not a JSON object")
+    if payload.get("version") != RECORD_VERSION:
+        raise PassRecordError(f"version {payload.get('version')!r} is not {RECORD_VERSION}")
+    if payload.get("stamp") != stamp:
+        raise PassRecordError(f"stamp {payload.get('stamp')!r} is not the file's {stamp!r}")
+    verdict = payload.get("verdict")
+    if verdict not in VERDICTS:
+        raise PassRecordError(f"verdict {verdict!r} is not one of {', '.join(VERDICTS)}")
+    branch = payload.get("branch")
+    plan_id = payload.get("planId")
+    if verdict == VERDICT_PLAN:
+        match = _BRANCH_RE.match(branch) if isinstance(branch, str) else None
+        if match is None or match.group(1) != stamp:
+            raise PassRecordError(f"branch {branch!r} is not PLAN-{stamp}-<slug>")
+        if not isinstance(plan_id, str) or not _PLAN_ID_RE.match(plan_id):
+            raise PassRecordError(f"planId {plan_id!r} is not <yyyy-mm-dd>-<slug>")
+    else:
+        branch = None
+        plan_id = None
+    skipped: list[Skip] = []
+    raw_skipped = payload.get("skipped", [])
+    if not isinstance(raw_skipped, list):
+        raise PassRecordError("skipped is not a list")
+    for index, item in enumerate(raw_skipped):
+        if not isinstance(item, dict) or not isinstance(item.get("key"), str) or not item["key"].strip():
+            raise PassRecordError(f"skipped[{index}] has no key")
+        reason = item.get("reason")
+        if not isinstance(reason, str) or not _REASON_RE.match(reason):
+            raise PassRecordError(f"skipped[{index}].reason {reason!r} is not one lowercase word")
+        skipped.append(Skip(key=item["key"].strip()[:200], reason=reason))
+    raw_amended = payload.get("amended", [])
+    if not isinstance(raw_amended, list) or not all(
+        isinstance(n, int) and not isinstance(n, bool) and n > 0 for n in raw_amended
+    ):
+        raise PassRecordError("amended is not a list of PR numbers")
+    return PassRecord(
+        stamp=stamp, verdict=str(verdict), branch=branch, plan_id=plan_id,
+        skipped=tuple(skipped), amended=tuple(dict.fromkeys(raw_amended)),
+    )