@bluewombat/manager-github 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# Manager: GitHub Issues
+
+The FeatureManager triplet for GitHub Issues: issues in, issue comments (and
+optional state labels) out, over the REST API with a token.
+Contract: [SPECS.md](./SPECS.md).
+
+```bash
+npm install @bluewombat/runtime @bluewombat/manager-github
+npx mason init --manager @bluewombat/manager-github --manager-option repo=owner/name
+export GITHUB_TOKEN=…
+```
+
+```json
+{
+  "manager": "@bluewombat/manager-github",
+  "managerOptions": {
+    "repo": "owner/name",
+    "labels": ["mason"],
+    "readyLabel": "ready",
+    "defaultProject": "app",
+    "stateLabelPrefix": "mason:"
+  }
+}
+```
+
+The token is read by this package from the environment; it never appears in the
+config file and Host never sees it.
+
+## What an issue says
+
+The body is the intention, word for word, less what GitHub itself put there:
+the comments an issue template leaves behind, and the boxes of a task list —
+`- [ ] a CSV downloads` reaches the Planner as `- a CSV downloads`. Nothing is
+read out of it: no checklist is required, no criteria are extracted (what
+"done" means is the layer above mason's, not mason's). A body that was only a
+template's comments falls back to the title.
+
+That text, with the title, the project and the priority, is the issue's
+fingerprint — what tells an **edit** from an **echo**. Comments, state labels
+and a ticked box all move `updated_at` and deliver the issue again; none of
+them changes the fingerprint. Rewording the body does, and on a Feature in
+flight that is recorded and freezes it once the current unit lands, for a
+human to decide. So: tick the boxes as you please; rewrite the words only when
+you mean it.
+
+## Options
+
+| Option             | Required | Default                         | Meaning                                                                                                                                                                                                                                                                                                           |
+| ------------------ | -------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `repo`             | yes      | —                               | `owner/name` to poll                                                                                                                                                                                                                                                                                              |
+| `tokenEnv`         | no       | `GITHUB_TOKEN`                  | Environment variable holding the token                                                                                                                                                                                                                                                                            |
+| `token`            | no       | —                               | The token itself. For embedding and tests; prefer `tokenEnv`                                                                                                                                                                                                                                                      |
+| `apiBase`          | no       | `https://api.github.com`        | REST base, for GitHub Enterprise                                                                                                                                                                                                                                                                                  |
+| `labels`           | no       | none                            | Every listed label must be on the issue for it to be admitted                                                                                                                                                                                                                                                     |
+| `readyLabel`       | no       | `ready`                         | On an escalated Feature, this label means resume                                                                                                                                                                                                                                                                  |
+| `defaultProject`   | no       | `unknown`                       | Project when no `project:` label says otherwise                                                                                                                                                                                                                                                                   |
+| `defaultPriority`  | no       | `50`                            | Priority when no `priority:` label says otherwise (0…100)                                                                                                                                                                                                                                                         |
+| `stateLabelPrefix` | no       | none                            | When set, state labels (`mason:done`, …) are moved too                                                                                                                                                                                                                                                            |
+| `branch`           | no       | `main`                          | The work line pull requests are opened onto. `mason setup` checks it exists and names the repository's default branch when it does not                                                                                                                                                                            |
+| `remote`           | no       | `https://github.com/<repo>.git` | Git URL of the repository, for Host's copy of the work line. Over HTTPS, git authenticates with the token in `tokenEnv` — read when git asks, never written to disk — so pushes are the token's account. Set it for GitHub Enterprise, a mirror, or SSH (then this machine's keys are used, and `doctor` says so) |
+| `keepBranch`       | no       | `false`                         | Leave the feature branch on the remote after the fold. By default it is deleted once the squash is on the work line                                                                                                                                                                                               |
+| `commitAuthor`     | no       | none                            | `Name <email>`: who the system is on the commits it makes. Without it, commits carry this machine's git identity, and `doctor` warns. Use the token's account (its noreply address works) so GitHub credits the system, not a person                                                                              |
+
+## Submissions
+
+This manager is an Authority: it offers an assembled feature to the repository
+as a pull request, and takes an accepted one in.
+
+| Method    | On GitHub                                                                                                                                                                                                    |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `submit`  | Opens a pull request from the published branch onto `workLine.branch`. An open one on the same branch is reused, never duplicated                                                                            |
+| `verdict` | Reads the checks on the pull request's head commit                                                                                                                                                           |
+| `fold`    | Squash-merges it: the commit's title is the pull request's; its body is what the Project's Describer said (carried on the pull request), else `Closes #N` alone. Then deletes the branch unless `keepBranch` |
+
+The pull request is titled after the issue (trailing full stop dropped, `(#N)`
+appended) and its body is the issue's intention, the Plan's steps, and
+`Closes #N` — so GitHub closes the issue when the pull request is merged.
+Nothing in it is generated.
+
+`verdict` counts the grace for a commit with no check from the **commit**, not
+from the pull request: one that was sent back and published again is old while
+its commit is seconds old, and reading "no check yet" as "no checks exist" folds
+it unjudged.
+
+`clearReady` takes the `readyLabel` off an issue once a resume has been acted
+on, so an escalation freezes instead of resuming on every pass.
+
+`probe` asks whether an issue Host already holds is still there. A poll cannot
+see a deletion: the issue is simply missing from every later page. Open is
+present; closed or 404 is gone (Host treats that as abandon). Any other error
+is unavailable, so a missed read does not cancel work.
+
+`referenceManager` names where the reference work line is — `remote` and
+`branch` — and who the system is there — `credentialEnv` (the token variable,
+for an HTTPS remote) and `author` (from `commitAuthor`) — in the words
+`@bluewombat/isolation-git` reads. With it, Host keeps its own copy at
+`<home>/work-line` (`.mason` by default) and `workLine.stable` need not be set.
+
+One rule about identity: the only thing done in a person's name is the issue
+they wrote. Comments, labels, pull requests and merges are the token's
+account; commits are `commitAuthor`; pushes and fetches use the token. A copy
+made before `remote` changed (SSH to HTTPS, say) no longer matches: delete it
+and the next run clones again.
+
+## Prepare the repository
+
+`mason setup` reads the config and says what the repository still needs;
+`--apply` creates it. It is idempotent, so it is safe to re-run after changing
+`labels` or turning `stateLabelPrefix` on.
+
+```bash
+mason setup --apply
+```
+
+| Checked                     | How                                                                                                                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| The repository is reachable | `GET /repos/{owner}/{repo}` — a 404 means "not found, or this token cannot see it"                                                                                                         |
+| Issues are enabled          | `has_issues` on that same response                                                                                                                                                         |
+| The token can write         | `permissions.push` on that same response, rather than guessing at scopes                                                                                                                   |
+| The branch exists           | `GET /repos/{owner}/{repo}/branches/{branch}` for `branch` (default `main`); when it is missing and the config named none, the step says the repository's default branch and what to write |
+| Labels                      | `labels`, `readyLabel`, `project:<defaultProject>`, and one per Event when `stateLabelPrefix` is set                                                                                       |
+
+Creating a label is the only write; nothing existing is renamed, recoloured, or
+deleted.
+
+## Stack
+
+Repository stack — TypeScript, Node 24.20, Biome, `node:test`. See [docs/DEVELOPMENT.md](../../../docs/DEVELOPMENT.md).
+
+## Setup
+
+From the repository root:
+
+```bash
+nvm use
+npm install
+```
+
+## Commands
+
+| Task      | Command          |
+| --------- | ---------------- |
+| Lint      | `npm run lint`   |
+| Format    | `npm run format` |
+| Typecheck | `npm run tsc`    |
+| Test      | `npm test`       |
+| Build     | `npm run build`  |
+
+## Layout
+
+```
+SPECS.md          the contract
+README.md         how to build and configure it
+src/
+  index.ts        createManager, checkManager, scaffoldManager — the plugin face
+  manager.ts      the ManagerPort (listen / adapt / report / probe live in listener/, adapter/, emitter/, probe/)
+  github/         Octokit channel shared by listen, adapt, report, and probe
+  probe/          whether a minted key's issue is still on the tracker
+  repo.ts         owner/name
+  issue-number.ts the issue a key or a payload points at
+  labels.ts       whether a payload carries a label
+```

package/SPECS.md

@@ -0,0 +1,126 @@
+# Manager: GitHub Issues
+
+A plugin, not a Transformer. GitHub Issues in, issue comments (and optional
+state labels) out, as one `ManagerPort`. Listen / adapt / report live in this
+package. GitHub-the-git-host is out of scope — only the tracker.
+
+## 1. Job
+
+```
+  Host                          manager-github
+  ----                          --------------
+  managerOptions                read repo / labels / token
+  a Cursor                      poll the issue list
+  a key                         probe: is the issue still there
+  one semantic Event            comment, and maybe label
+  a published branch            submit: open (or reuse) the pull request
+  a Submission reference        fold: squash-merge it, delete the branch unless keepBranch
+                            ←   ManagerPort
+```
+
+**In:** a `ManagerContext`. **Out:** a `ManagerPort`, or a reason.
+
+## 2. The token
+
+Read from `context.env[tokenEnv]`, defaulting to `GITHUB_TOKEN`. A `token`
+option exists for embedding and tests. `createManager` refuses with the name of
+the variable it wanted when neither is set — the value is never echoed, logged,
+or written to a Thread.
+
+## 3. Keys
+
+`github:<owner>/<name>#<issue>`, or `github:unconvertible` when the payload
+carries no issue number. `report` recovers the issue from the key: every key
+this package mints ends in `#<issue>`, so no issue number crosses the Port.
+
+## 3b. The intention and its fingerprint
+
+The issue body is the intention, verbatim, less what the tracker itself put
+there: the HTML comments an issue template leaves behind, and the boxes of a
+task list (`- [ ]`, `- [x]` — the bullet and the words stay). Line ends are
+normalised, trailing blanks and runs of blank lines collapsed. Nothing is read:
+no criteria, no headings, no meaning. A body that was only that falls back to
+the title, like no body at all.
+
+The FeatureStandard's `fingerprint` hashes that intention with the title, the
+project and the priority. It is what tells an **edit** from an **echo** — a
+comment or a state label moves `updated_at` and delivers the issue again, and
+so does a human ticking a box. None of those is a change of mind, so none of
+them changes the fingerprint; a different fingerprint on a Feature in flight
+is recorded as pending and freezes it once the current unit lands
+(PRODUCT.md, "An intention edited while in flight"). Rewording the body is an
+edit. Ticking a box is not.
+
+## 4. Ready
+
+`signalsReady` is true when the payload carries `readyLabel`, ignoring case, in
+either label spelling GitHub uses (a string, or an object with `name`). A poll
+returns a snapshot with no `labeled` edge, so the label on the snapshot is the
+only signal there is.
+
+## 5. Setup
+
+`setupManager` is the only part of this package that writes to GitHub before a
+run. It reads the repository once — that single response answers reachable,
+issues enabled, and whether the token may write — then lists the labels the
+configuration names against the labels that exist.
+
+Without `apply` it reports a plan and sends no `POST`. With `apply` it creates
+the missing labels and nothing else: an existing label is never renamed,
+recoloured, or deleted, and a repeated name is created once. A second `apply`
+reports everything `satisfied`.
+
+A 404 on the repository is reported as "not found, or this token cannot see
+it", because from here the two are the same answer.
+
+## 6. Doctor
+
+`checkManager` reports the repository, whether the token variable is set
+(`fail` when it is not), whether labels narrow the Source (`warn` when they do
+not — every open issue would be admitted), and reminds which labels the
+repository needs. It never calls the API: the answer must be the same offline.
+
+## 6. Init
+
+`scaffoldManager` fills `repo`, `tokenEnv`, `labels`, `readyLabel` and
+`defaultProject`. It does not create labels on the repository: that needs the
+network, and the operator still owns the tracker. A `repo` already in
+`managerOptions` is kept.
+
+## 7. Probe
+
+`probe` recovers the issue from the key (`github:<owner>/<name>#<n>`) and
+`GET`s it. Open is `present`. Closed is `gone` — the same intent as a cancel
+delivery. A 404 or 410 is `gone` too (deleted, or transferred). Anything else
+— a 401, a 403, a 5xx, a body that is not an issue — is `unavailable`. A key
+with no issue number is `unavailable`, not `gone`.
+
+`fetchIssue` still treats every failure as `unavailable`: a Fetch that did
+not answer says nothing about the intention being converted. Probe is the
+path that may read a 404 as absence.
+
+## 8. Acceptance
+
+1. A token in the variable named by `tokenEnv` is enough to build the Port.
+2. No token → a reason naming the variable it looked in.
+3. A missing `repo`, a `repo` that is not `owner/name`, and an unknown option
+   key each return a reason.
+4. `checkManager` fails on a missing token and warns when no label is set.
+5. `setup` without `apply` writes nothing; with `apply` it creates only the
+   missing labels, and a second `apply` writes nothing at all.
+6. Disabled issues, a read-only token, and an unreachable repository each block
+   before any label is created.
+7. `scaffoldManager` keeps a `repo` it was given and names `GITHUB_TOKEN`.
+8. `invalid`, `accepted`, `planned`, `escalated` and `resumed` comments are
+   written as string literals, not a field dump. An `invalid` comment is the
+   heading and the reason as a paragraph, with no `- reason:` bullet.
+9. `probe` of an open issue is `present`; closed or 404 is `gone`; 403 is
+   `unavailable`. A key with no issue number does not call the API.
+10. A template's HTML comments and a task list's boxes leave the intention;
+    the bullet and the words stay. The same body with a box ticked normalises
+    to the same intention and the same fingerprint. A body that was only
+    noise falls back to the title.
+11. `setup` blocks on a `branch` the repository does not have, and names the
+    repository's default branch when the config named none.
+
+How to build and configure: [README.md](./README.md).

package/dist/adapter/github/fetch-issue.d.ts

@@ -0,0 +1,29 @@
+import { type GithubClient } from "../../github/client.js";
+import type { Invocation } from "../types.js";
+export type FetchResult = 
+/** The issue as the API holds it now: the base the raw intention is layered on. */
+{
+    kind: "merged";
+    issue: Record<string, unknown>;
+}
+/** Nothing is known about the intention. The same call may answer later. */
+ | {
+    kind: "unavailable";
+    detail: string;
+} | {
+    kind: "interrupted";
+};
+export type FetchRequest = {
+    invocation: Invocation;
+    github: GithubClient;
+    number: number;
+    deadlineMs: number;
+    now: () => number;
+    shouldInterrupt: () => boolean;
+};
+/**
+ * Re-read the issue. Every failure is `unavailable`, never `invalid`: a Fetch
+ * that did not answer says nothing about the intention.
+ */
+export declare function fetchIssue(request: FetchRequest): Promise<FetchResult>;
+//# sourceMappingURL=fetch-issue.d.ts.map

package/dist/adapter/github/fetch-issue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-issue.d.ts","sourceRoot":"","sources":["../../../src/adapter/github/fetch-issue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,YAAY,EAAe,MAAM,wBAAwB,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,WAAW;AACrB,mFAAmF;AACjF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE;AACpD,4EAA4E;GAC1E;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAE5B,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,OAAO,CAAC;CAChC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA4B5E"}

package/dist/adapter/github/fetch-issue.js

@@ -0,0 +1,34 @@
+import { callSignal, readFailure } from "../../github/client.js";
+/**
+ * Re-read the issue. Every failure is `unavailable`, never `invalid`: a Fetch
+ * that did not answer says nothing about the intention.
+ */
+export async function fetchIssue(request) {
+    const call = callSignal(request.deadlineMs, request.now, request.shouldInterrupt);
+    try {
+        const response = await request.github.request("GET /repos/{owner}/{repo}/issues/{issue_number}", {
+            owner: request.invocation.repo.owner,
+            repo: request.invocation.repo.name,
+            issue_number: request.number,
+            request: { signal: call.signal },
+        });
+        const issue = response.data;
+        if (issue === null || typeof issue !== "object" || Array.isArray(issue)) {
+            return {
+                kind: "unavailable",
+                detail: "The Fetch answered with something other than an issue.",
+            };
+        }
+        return { kind: "merged", issue: issue };
+    }
+    catch (error) {
+        if (request.shouldInterrupt()) {
+            return { kind: "interrupted" };
+        }
+        return { kind: "unavailable", detail: readFailure(error).detail };
+    }
+    finally {
+        call.release();
+    }
+}
+//# sourceMappingURL=fetch-issue.js.map

package/dist/adapter/github/fetch-issue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-issue.js","sourceRoot":"","sources":["../../../src/adapter/github/fetch-issue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAqB,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAmBpF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAqB;IACpD,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAClF,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAC3C,iDAAiD,EACjD;YACE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK;YACpC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI;YAClC,YAAY,EAAE,OAAO,CAAC,MAAM;YAC5B,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;SACjC,CACF,CAAC;QACF,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAe,CAAC;QACvC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACxE,OAAO;gBACL,IAAI,EAAE,aAAa;gBACnB,MAAM,EAAE,wDAAwD;aACjE,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAgC,EAAE,CAAC;IACrE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QACjC,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;IACpE,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/adapter/normalize/body.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Reading an issue body. Pure: no clock, no request, no file.
+ *
+ * A body is free text a human wrote in a web form. Two shapes are recognised —
+ * a task list, and an acceptance section — because those are the two shapes
+ * GitHub itself renders as a checklist. Everything else stays intention text.
+ */
+export type BodyParts = {
+    /** The free text left once the criteria were taken out; absent when empty. */
+    intention?: string;
+    criteria: string[];
+};
+/** Comments an issue template left behind are not something a human wrote. */
+export declare function stripComments(body: string): string;
+/**
+ * Split a body into the intention and its acceptance criteria.
+ *
+ * Task-list items win wherever they are: `- [ ] …` is the checklist GitHub
+ * renders, and a human who wrote one meant it. Without any, a section titled
+ * "acceptance criteria" (or "definition of done") is read instead, and the whole
+ * section leaves the intention.
+ */
+export declare function readBody(body: string): BodyParts;
+//# sourceMappingURL=body.d.ts.map

package/dist/adapter/normalize/body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../../../src/adapter/normalize/body.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,MAAM,SAAS,GAAG;IACtB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAcD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAkChD"}

package/dist/adapter/normalize/body.js

@@ -0,0 +1,104 @@
+/**
+ * Reading an issue body. Pure: no clock, no request, no file.
+ *
+ * A body is free text a human wrote in a web form. Two shapes are recognised —
+ * a task list, and an acceptance section — because those are the two shapes
+ * GitHub itself renders as a checklist. Everything else stays intention text.
+ */
+const TASK_ITEM = /^\s*[-*+]\s+\[[ xX]\]\s+(.*\S)\s*$/;
+const HEADING = /^\s{0,3}#{1,6}\s+(.*\S)\s*$/;
+const BULLET = /^\s*(?:[-*+]|\d+[.)])\s+(.*\S)\s*$/;
+/** Headings whose section is a list of criteria rather than intention text. */
+const CRITERIA_HEADINGS = new Set(["acceptance criteria", "definition of done"]);
+/** Comments an issue template left behind are not something a human wrote. */
+export function stripComments(body) {
+    return body.replace(/<!--[\s\S]*?-->/g, "");
+}
+function headingTitle(line) {
+    const matched = HEADING.exec(line);
+    return matched?.[1] === undefined ? null : normalizeTitle(matched[1]);
+}
+function normalizeTitle(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+/**
+ * Split a body into the intention and its acceptance criteria.
+ *
+ * Task-list items win wherever they are: `- [ ] …` is the checklist GitHub
+ * renders, and a human who wrote one meant it. Without any, a section titled
+ * "acceptance criteria" (or "definition of done") is read instead, and the whole
+ * section leaves the intention.
+ */
+export function readBody(body) {
+    const lines = stripComments(body).replace(/\r\n?/g, "\n").split("\n");
+    const criteria = [];
+    const kept = [];
+    for (const line of lines) {
+        const task = TASK_ITEM.exec(line);
+        if (task?.[1] !== undefined) {
+            criteria.push(task[1].trim());
+            continue;
+        }
+        kept.push(line);
+    }
+    if (criteria.length > 0) {
+        return parts(dropEmptiedCriteriaHeadings(kept), criteria);
+    }
+    const start = lines.findIndex((line) => {
+        const title = headingTitle(line);
+        return title !== null && CRITERIA_HEADINGS.has(title);
+    });
+    if (start === -1) {
+        return parts(lines, []);
+    }
+    let end = start + 1;
+    while (end < lines.length && headingTitle(lines[end] ?? "") === null) {
+        const bullet = BULLET.exec(lines[end] ?? "");
+        if (bullet?.[1] !== undefined) {
+            criteria.push(bullet[1].trim());
+        }
+        end += 1;
+    }
+    return parts([...lines.slice(0, start), ...lines.slice(end)], criteria);
+}
+/**
+ * Drop a criteria heading whose section the task list just emptied.
+ *
+ * `## Acceptance criteria` followed by `- [ ] …` items loses its items to the
+ * task list above, and a bare heading with nothing under it would otherwise
+ * travel on as intention text — into the Plan, and into the Builder's prompt.
+ * A heading that still has prose under it stays: that prose is intention.
+ */
+function dropEmptiedCriteriaHeadings(lines) {
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const title = headingTitle(lines[i] ?? "");
+        if (title === null || !CRITERIA_HEADINGS.has(title)) {
+            out.push(lines[i] ?? "");
+            continue;
+        }
+        let end = i + 1;
+        while (end < lines.length && headingTitle(lines[end] ?? "") === null) {
+            end += 1;
+        }
+        if (lines.slice(i + 1, end).some((line) => line.trim().length > 0)) {
+            out.push(...lines.slice(i, end));
+        }
+        i = end - 1;
+    }
+    return out;
+}
+function parts(kept, criteria) {
+    const intention = kept
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    return {
+        ...(intention.length > 0 ? { intention } : {}),
+        criteria: criteria.filter((entry) => entry.length > 0),
+    };
+}
+//# sourceMappingURL=body.js.map

package/dist/adapter/normalize/body.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.js","sourceRoot":"","sources":["../../../src/adapter/normalize/body.ts"],"names":[],"mappings":"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"}

package/dist/adapter/normalize/fingerprint.d.ts

@@ -0,0 +1,8 @@
+/** JSON with object keys sorted, so two equal documents hash the same. */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Answers "did this intention change?". Covers every field of the
+ * FeatureStandard except the two that are not the intention itself.
+ */
+export declare function fingerprintOf(document: Record<string, unknown>): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/adapter/normalize/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../../src/adapter/normalize/fingerprint.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAKvE"}

package/dist/adapter/normalize/fingerprint.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+/** JSON with object keys sorted, so two equal documents hash the same. */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalJson(entryValue)}`);
+    return `{${entries.join(",")}}`;
+}
+/**
+ * Answers "did this intention change?". Covers every field of the
+ * FeatureStandard except the two that are not the intention itself.
+ */
+export function fingerprintOf(document) {
+    const subject = { ...document };
+    delete subject.fingerprint;
+    delete subject.normalized_at;
+    return `sha256:${createHash("sha256").update(canonicalJson(subject)).digest("hex")}`;
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/adapter/normalize/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../../src/adapter/normalize/fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACzC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACnD,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC;SACpD,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SACrE,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACrF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAiC;IAC7D,MAAM,OAAO,GAA4B,EAAE,GAAG,QAAQ,EAAE,CAAC;IACzD,OAAO,OAAO,CAAC,WAAW,CAAC;IAC3B,OAAO,OAAO,CAAC,aAAa,CAAC;IAC7B,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACvF,CAAC"}

package/dist/adapter/normalize/intent.d.ts

@@ -0,0 +1,27 @@
+import type { Intent, Invalid } from "../types.js";
+/** What a repository can say about an issue, in this Block's five words. */
+export type Kind = "create" | "update" | "ready" | "cancel" | "delete";
+export type IntentInput = {
+    action: string | undefined;
+    state: string | undefined;
+    labels: string[];
+    readyLabel: string;
+};
+export type IntentResult = {
+    ok: true;
+    intent: Intent;
+} | {
+    ok: false;
+    invalid: Invalid;
+};
+/**
+ * Collapse what happened into one of three intents.
+ *
+ * With an action, the repository said what changed. Without one — a snapshot a
+ * subscription listed — only the state is known: open means the intention
+ * itself, closed means drop it. `ready` needs the edge, not the state: it is the
+ * moment the label arrived, and a snapshot cannot tell that from a label that
+ * has been there for a week.
+ */
+export declare function readIntent(input: IntentInput): IntentResult;
+//# sourceMappingURL=intent.d.ts.map

package/dist/adapter/normalize/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../../src/adapter/normalize/intent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGnD,4EAA4E;AAC5E,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AA+BvE,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1F;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAmB3D"}

package/dist/adapter/normalize/intent.js

@@ -0,0 +1,57 @@
+import { hasLabel } from "./labels.js";
+const ACTION_TO_KIND = {
+    opened: "create",
+    reopened: "create",
+    edited: "update",
+    labeled: "update",
+    unlabeled: "update",
+    assigned: "update",
+    unassigned: "update",
+    milestoned: "update",
+    demilestoned: "update",
+    pinned: "update",
+    unpinned: "update",
+    locked: "update",
+    unlocked: "update",
+    typed: "update",
+    untyped: "update",
+    closed: "cancel",
+    deleted: "delete",
+    transferred: "delete",
+};
+const KIND_TO_INTENT = {
+    create: "upsert",
+    update: "upsert",
+    ready: "ready",
+    cancel: "cancel",
+    delete: "cancel",
+};
+/**
+ * Collapse what happened into one of three intents.
+ *
+ * With an action, the repository said what changed. Without one — a snapshot a
+ * subscription listed — only the state is known: open means the intention
+ * itself, closed means drop it. `ready` needs the edge, not the state: it is the
+ * moment the label arrived, and a snapshot cannot tell that from a label that
+ * has been there for a week.
+ */
+export function readIntent(input) {
+    if (input.action === undefined) {
+        return { ok: true, intent: input.state === "closed" ? "cancel" : "upsert" };
+    }
+    const kind = ACTION_TO_KIND[input.action];
+    if (kind === undefined) {
+        return {
+            ok: false,
+            invalid: {
+                code: "unknown-action",
+                reason: `Action "${input.action}" is not one this Block reads.`,
+            },
+        };
+    }
+    if (input.action === "labeled" && hasLabel(input.labels, input.readyLabel)) {
+        return { ok: true, intent: KIND_TO_INTENT.ready };
+    }
+    return { ok: true, intent: KIND_TO_INTENT[kind] };
+}
+//# sourceMappingURL=intent.js.map

package/dist/adapter/normalize/intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.js","sourceRoot":"","sources":["../../../src/adapter/normalize/intent.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAKvC,MAAM,cAAc,GAAyB;IAC3C,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,QAAQ;IAClB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,QAAQ;IACjB,SAAS,EAAE,QAAQ;IACnB,QAAQ,EAAE,QAAQ;IAClB,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE,QAAQ;IACpB,YAAY,EAAE,QAAQ;IACtB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,QAAQ;IAClB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,QAAQ;IAClB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,QAAQ;IACjB,WAAW,EAAE,QAAQ;CACtB,CAAC;AAEF,MAAM,cAAc,GAAyB;IAC3C,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACjB,CAAC;AAWF;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAkB;IAC3C,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC9E,CAAC;IAED,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE;gBACP,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,WAAW,KAAK,CAAC,MAAM,gCAAgC;aAChE;SACF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,KAAK,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;AACpD,CAAC"}