@bluewombat/manager-github 0.8.0 → 0.10.0

package/README.md

@@ -1,7 +1,10 @@
 # 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.
+The FeatureTracker and TicketTracker for GitHub Issues: a Feature is an issue
+carrying `feature-ready`, its Tickets are its sub-issues carrying `task-ready`;
+comments (and optional state labels) go out, over the REST API with a token.
+The same repository is the Authority: it cuts the lines and holds the pull
+requests.
 Contract: [SPECS.md](./SPECS.md).
 
 ```bash
@@ -10,27 +13,78 @@ npx mason init --manager @bluewombat/manager-github --manager-option repo=owner/
 export GITHUB_TOKEN=…
 ```
 
-```json
-{
-  "manager": "@bluewombat/manager-github",
-  "managerOptions": {
-    "repo": "owner/name",
-    "labels": ["mason"],
-    "readyLabel": "ready",
-    "defaultProject": "app",
-    "stateLabelPrefix": "mason:"
-  }
-}
+```yaml
+featureTracker:
+  package: "@bluewombat/manager-github"
+  options:
+    repo: owner/name
+    featureReadyLabel: feature-ready
+    mergeWhenReadyLabel: merge-when-ready
+    resumeLabel: to-resume
+    defaultProject: app
+    stateLabels: &stateLabels
+      invalid: "mason:invalid"
+      accepted: "mason:accepted"
+      progress: "mason:progress"
+      escalated: "mason:escalated"
+      escalation_reminder: "mason:escalation_reminder"
+      resumed: "mason:resumed"
+      submitted: "mason:submitted"
+      done: "mason:done"
+      cancelled: "mason:cancelled"
+      reject_late: "mason:reject_late"
+ticketTracker:
+  package: "@bluewombat/manager-github"
+  options:
+    repo: owner/name
+    ticketReadyLabel: task-ready
+    resumeLabel: to-resume
+    defaultProject: app
+    stateLabels: *stateLabels
 ```
 
+Each label option is written under the side that uses it:
+`featureReadyLabel` and `mergeWhenReadyLabel` under `featureTracker`,
+`ticketReadyLabel`, `noTestsLabel` and `e2eLabel` under `ticketTracker`; `skipTestE2eLabel` under `featureTracker`. The package is told which side it
+serves, so `mason setup` creates only that side's labels and `mason doctor`
+names only those; an option under the wrong side is refused by name. The
+options both sides read (`repo`, `tokenEnv`, `resumeLabel`, `defaultProject`,
+`stateLabels`, …) are written under both.
+
+A config that gives both sides the same options (a YAML anchor, say) builds one
+manager serving both: every option is then accepted, and the label options may
+share one name.
+
+The same package answers both sides here; a Feature tracker of another tool
+takes the first block alone (Features), and this package the second (Tickets,
+lines).
+
 The token is read by this package from the environment; it never appears in the
 config file and Host never sees it.
 
+## Features and Tickets
+
+| On GitHub                                     | Means                                                                                                            |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| A top-level issue with `feature-ready`          | A Feature: its content is final, its Tickets may be written. Only these are listed. A sub-issue is never a Feature |
+| Its sub-issues                                | Its Tickets, in the order GitHub gives them                                                                      |
+| `task-ready` on a sub-issue                    | The Ticket's specification is final. A Feature starts only when every one of its Tickets carries it             |
+| "Blocked by" (issue dependencies)             | On a Feature: the Features that must be done first. On a Ticket: the Tickets that must be done first            |
+| `skip-test-e2e` on a Feature                  | The Feature is not put through the e2e acceptance check: its e2e Ticket is cancelled and the Gate that runs the suite is not run. Put on or taken off, it is read again until the Feature is submitted |
+| `e2e` on a sub-issue                          | The Ticket holds the e2e acceptance suite of its Feature: it is made by the e2e pass, with no tests written first |
+| `merge-when-ready` on a Feature               | Its line may be folded without a human. Without it, a human merges the pull request and the system waits         |
+| `to-resume` on an escalated Feature or Ticket | Resume                                                                                                           |
+| `priority:<n>`, `project:<name>` labels       | On a Feature and on a Ticket                                                                          |
+
+The Feature and Ticket labels may share one name (`featureReadyLabel` and
+`ticketReadyLabel` both `ready-for-agent`): a sub-issue is a Ticket whatever it
+carries, and `mason setup` creates the label once.
+
 ## 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
+`- [ ] a CSV downloads` reaches the Builder 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.
@@ -38,7 +92,7 @@ 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
+them changes the fingerprint. Rewording the body does, and on a Ticket 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.
@@ -51,30 +105,40 @@ you mean it.
 | `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; the escalation comment names it                                                                                                                                                                                                                                 |
-| `defaultProject`   | no       | `unknown`                       | Project when no `project:` label says otherwise                                                                                                                                                                                                                                                                   |
+| `featureReadyLabel` (featureTracker) | no       | `feature-ready`                   | The label that makes an issue a Feature the system may take                                                                                                                                                                                                                                                       |
+| `ticketReadyLabel` (ticketTracker) | no       | `task-ready`                     | The label a sub-issue carries once its specification is final                                                                                                                                                                                                                                                     |
+| `noTestsLabel` (ticketTracker) | no       | `no-tests`                       | The label that says no tests are written before this Ticket's code. It is read on the sub-issue, beside its text: the Ticket is made without the agent that writes tests first (see No tests first)                                                                                                         |
+| `e2eLabel` (ticketTracker) | no       | `e2e`                            | The label that says this sub-issue holds the Feature's e2e acceptance suite (see The e2e labels) |
+| `skipTestE2eLabel` (featureTracker) | no | `skip-test-e2e`                  | On a Feature: it is not put through the e2e acceptance check |
+| `mergeWhenReadyLabel` (featureTracker) | no    | `merge-when-ready`              | On a Feature: its line is folded without a human                                                                                                                                                                                                                                                                  |
+| `resumeLabel`       | no       | `to-resume`                         | On an escalated Feature or Ticket, this label means resume; the escalation comment names it                                                                                                                                                                                                                                 |
+| `defaultProject`   | no       | none                            | The Project of a Feature that has no `project:` label. Without it, such a Feature is refused as invalid (`missing-project`). `mason setup` creates the label `project:<defaultProject>` |
 | `defaultPriority`  | no       | `50`                            | Priority when no `priority:` label says otherwise (0…100)                                                                                                                                                                                                                                                         |
-| `stateLabelPrefix` | no       | none                            | When set, state labels (`mason:done`, …) are moved too                                                                                                                                                                                                                                                            |
+| `stateLabels`      | no       | none                            | A mapping that names, for every Event, the label it lands as (see State labels). Absent: the Events leave no label |
+| `labelColors`      | no       | none                            | A colour for each kind of label the setup creates, by what it is for, not by its name (see Label colours) |
 | `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                                                                                                                                                                                               |
+| `keepBranch`       | no       | `false`                         | Leave the ticket 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.
+This manager is an Authority: it cuts the line of a Feature, offers an
+assembled Ticket (or a Feature's line) 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                                                                                                                                                           |
+| `openLine`| Creates `feature/<n>` from `branch` (`git/refs`). A line that exists is a success                                                                                                                            |
+| `dropLine`| Deletes a line nobody will fold                                                                                                                                                                              |
+| `submit`  | Opens a pull request from the published branch onto the line it is offered to (a Feature's line, or `branch`). An open one on the same branch is reused, never duplicated                                   |
+| `settled` | Whether the pull request is still open, was merged (by anyone), or was closed unmerged. A human's merge is read here                                                                                         |
+| `behind`  | Whether the line holds commits the pull request does not (`compare` of the line's tip against the pull request's head, `behind_by`). Asked right before a `fold`. A failed read is `unavailable`, never `current` |
 | `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.
+appended) and its body is the issue's intention and
+`Closes #N` — so GitHub closes the issue when the pull request is merged. GitHub honours `Closes` only for a merge into the default branch, so a Ticket folded into a Feature's line stays open until a reservation says otherwise (`docs/RESERVATIONS.md`).
 Nothing in it is generated.
 
 `verdict` counts the grace for a commit with no check from the **commit**, not
@@ -82,7 +146,7 @@ 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
+`clearResume` takes the `resumeLabel` 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
@@ -119,7 +183,7 @@ back whole, as the full read would have been. A 304 sent with an
 Authorization header does not count against the token's hourly budget
 (GitHub's [REST best practices](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api);
 measured: three 304s in a row left `x-ratelimit-used` unchanged). So a tick
-where nothing moved on the watched issues — the listing, a probe of a Feature
+where nothing moved on the watched issues — the listing, a probe of a Ticket
 in flight — costs a round trip and no budget. Handing the answer back rather
 than reading a 304 as "nothing" matters: when Host did not commit its Cursor,
 the same listing is asked again and the issues not consumed yet must come back.
@@ -130,11 +194,100 @@ per judgement, with nothing to remember an `etag` in. Anything this manager
 writes on an issue (a comment, a label) changes the listing, so the next read
 after a report is a full one.
 
+## State labels
+
+The Events are `invalid`, `accepted`, `progress`, `escalated`, `escalation_reminder`,
+`resumed`, `submitted`, `done`, `cancelled` and `reject_late`. With `stateLabels` set,
+the issue carries the label of its latest Event and the previous one is removed;
+every other label (`project:`, `priority:`, yours) is never touched. `done` and
+`cancelled` also keep a fresh Mason home from rebuilding or taking up an issue that
+already ended, unless the resume label is on it.
+
+`stateLabels` names every Event, with any label you like, and gives the same name to
+no two Events:
+
+```yaml
+options:
+  stateLabels:
+    invalid: "mason:invalid"
+    accepted: "mason:accepted"
+    progress: "mason:progress"
+    escalated: "mason:escalated"
+    escalation_reminder: "mason:escalation_reminder"
+    resumed: "mason:resumed"
+    submitted: "mason:submitted"
+    done: "termine"
+    cancelled: "abandonne"
+    reject_late: "mason:reject_late"
+```
+
+Absent, nothing is labelled and the guard on `done` and `cancelled` is off. Naming
+an Event outside the list, leaving one out, or giving a label twice is refused.
+
+## No tests first
+
+When the host writes a Ticket's tests before its code, a sub-issue carrying the `no-tests`
+label (the `noTestsLabel` option renames it) is made without that step: no agent writes
+tests for it, and its producer writes its own with its code. The decision is the label,
+never a line of the issue's text, so it can be set or taken off without editing the
+specification. Put it on a Ticket before it starts: a Ticket already under way keeps what
+it began with. `mason setup` creates the label, and `labelColors` colours it with the
+`no-tests` key.
+
+## The e2e labels
+
+A Project may prove each Feature by an acceptance suite run once on the whole Feature (see the
+runtime README, "The e2e acceptance check"). On the tracker it is two labels. `e2e`
+(`e2eLabel`, under `ticketTracker`) marks the last sub-issue of the Feature, whose body is the
+scenarios agreed with the operator, `E1`, `E2`…, copied verbatim; it must be blocked by every
+other sub-issue. `skip-test-e2e` (`skipTestE2eLabel`, under `featureTracker`) on the Feature
+leaves the check out: the `e2e` sub-issue is cancelled, and the Gate that runs the suite is not
+run. Both are compared without case, and read again on each delivery until the Feature is
+submitted. `mason setup` creates them, and `labelColors` colours them with the keys `e2e` and
+`skip-test-e2e`.
+
+## Label colours
+
+`mason setup` gives each label a colour so a human can tell them apart. `labelColors`
+chooses them, one label at a time. A key is the identifier of a label, never its name, so
+renaming a label (`stateLabels`, `resumeLabel`, ...) does not lose its colour. A colour is
+six hex digits, with or without a `#`:
+
+```yaml
+options:
+  labelColors:
+    feature-ready: "1d76db"
+    ticket-ready: "1d76db"
+    merge-when-ready: "1d76db"
+    no-tests: "fbca04"
+    e2e: "0e8a16"
+    skip-test-e2e: "fbca04"
+    resume: "0e8a16"
+    project: "c5def5" # project:<defaultProject>
+    state-invalid: "5319e7"
+    state-accepted: "5319e7"
+    state-progress: "5319e7"
+    state-escalated: "d93f0b"
+    state-escalation_reminder: "d93f0b"
+    state-resumed: "5319e7"
+    state-submitted: "5319e7"
+    state-done: "0e8a16"
+    state-cancelled: "6a737d"
+    state-reject_late: "6a737d"
+```
+
+Every key is optional. When the Feature and the Ticket ready labels are one label (the
+same name), `feature-ready` colours it. A colour the config chose is applied to a label
+that already exists too: `mason setup` says `recolour label …` and `--apply` does it. A
+label the config chose no colour for keeps the default colour when it is created and is
+never touched when it exists, so a colour set by hand on GitHub stays. A key that is not in
+the list above, or a colour that is not six hex digits, is refused by name.
+
 ## 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.
+the label options or setting `stateLabels`.
 
 ```bash
 mason setup --apply
@@ -146,10 +299,10 @@ mason setup --apply
 | 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                                                                                       |
+| Labels                      | `featureReadyLabel`, `ticketReadyLabel`, `noTestsLabel`, `e2eLabel`, `mergeWhenReadyLabel`, `skipTestE2eLabel`, `resumeLabel`, `project:<defaultProject>`, and one per Event when `stateLabels` is set                                                                                       |
 
-Creating a label is the only write; nothing existing is renamed, recoloured, or
-deleted.
+Creating a label, and recolouring one the config chose a colour for (see Label
+colours), are the only writes; nothing existing is renamed or deleted.
 
 ## Stack
 
@@ -181,10 +334,12 @@ 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/)
+  manager.ts      the Manager: `features` and `tickets` (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
+  tickets/        a Feature's sub-issues, their blockers and signals
+  submission/     lines, pull requests, settled
   issue-number.ts the issue a key or a payload points at
   labels.ts       whether a payload carries a label
 ```

package/SPECS.md

@@ -1,8 +1,9 @@
 # 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.
+A plugin, not a Transformer. GitHub Issues in (Features and their sub-issues),
+issue comments (and optional state labels) out, and the lines and pull requests
+of the same repository, as one `Manager` (`features` and `tickets`). Listen /
+adapt / report live in this package.
 
 ## 1. Job
 
@@ -10,15 +11,18 @@ package. GitHub-the-git-host is out of scope — only the tracker.
   Host                          manager-github
   ----                          --------------
   managerOptions                read repo / labels / token
-  a Cursor                      poll the issue list
+  a Cursor                      poll the issues labelled feature-ready
+  a Feature                     list its sub-issues and blockers
   a key                         probe: is the issue still there
   one semantic Event            comment, and maybe label
+  a Feature's line              openLine: cut feature/<n>; dropLine
   a published branch            submit: open (or reuse) the pull request
-  a Submission reference        fold: squash-merge it, delete the branch unless keepBranch
-                            ←   ManagerPort
+  a Submission reference        fold: squash-merge it, delete the branch unless keepBranch;
+                                settled: open / folded / closed
+                            ←   Manager
 ```
 
-**In:** a `ManagerContext`. **Out:** a `ManagerPort`, or a reason.
+**In:** a `ManagerContext`. **Out:** a `Manager`, or a reason.
 
 ## 2. The token
 
@@ -29,7 +33,7 @@ or written to a Thread.
 
 ## 3. Keys
 
-`github:<owner>/<name>#<issue>`, or `github:unconvertible` when the payload
+Features and Tickets share one spelling: `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.
 
@@ -42,18 +46,28 @@ 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
+The FeatureStandard's and TicketStandard'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
+them changes the fingerprint; a different fingerprint on a Ticket 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
+## 3c. Features and Tickets
 
-`signalsReady` is true when the payload carries `readyLabel`, ignoring case, in
+A Feature is listed when the issue has no parent (`parent_issue_url` is null) and carries `featureReadyLabel`
+(`labels=<featureReadyLabel>` on the list call). Its `blocked_by` are read from
+`GET /issues/{n}/dependencies/blocked_by`, its `merge_when_ready` from
+`mergeWhenReadyLabel` and its `skip_e2e` from `skipTestE2eLabel`. `tickets(feature)` reads `GET /issues/{n}/sub_issues`
+and, per sub-issue, its blockers; `task_ready` is `ticketReadyLabel`, `resume` is
+`resumeLabel`, `open` is the issue state. Every failed read is `unavailable`,
+never an empty list.
+
+## 4. Resume
+
+`signalsResume` is true when the payload carries `resumeLabel`, 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.
@@ -65,10 +79,12 @@ 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`.
+Without `apply` it reports a plan and sends no write. With `apply` it creates the
+missing labels, and recolours an existing label whose colour differs from the one the
+config chose for it (`labelColors`, keyed by the label's identifier: `feature-ready`,
+`ticket-ready`, `merge-when-ready`, `no-tests`, `e2e`, `skip-test-e2e`, `resume`, `project`, `state-<event>`): an existing label is never renamed or deleted, a label with no
+chosen colour keeps whatever colour it has, 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.
@@ -76,13 +92,12 @@ 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.
+(`fail` when it is not), and names the labels the repository needs (`featureReadyLabel`,
+`ticketReadyLabel`, `mergeWhenReadyLabel`, `resumeLabel`). It never calls the API: the answer must be the same offline.
 
 ## 6. Init
 
-`scaffoldManager` fills `repo`, `tokenEnv`, `labels`, `readyLabel` and
+`scaffoldManager` fills `repo`, `tokenEnv`, `resumeLabel` 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.
@@ -99,19 +114,33 @@ with no issue number is `unavailable`, not `gone`.
 not answer says nothing about the intention being converted. Probe is the
 path that may read a 404 as absence.
 
+## 7b. Lines
+
+`openLine({line, from})` reads `git/ref/heads/<from>` and creates `refs/heads/<line>`
+at that commit; a 422 (the ref exists) is a success. `dropLine` deletes the ref
+and ignores a refusal. `settled({reference})` reads the pull request: merged is
+`folded`, closed unmerged is `closed`, otherwise `open`.
+
+## 7c. Behind
+
+`behind({reference})` reads the pull request, the tip of the branch it is offered
+to (`git/ref/heads/<base>`), and compares the two by commit, `behind_by` of
+`<tip>...<head>`. `0` is `current`; more is `behind` with that count; any failed
+read, or an answer with no count, is `unavailable`. It writes nothing.
+
 ## 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.
+4. `checkManager` fails on a missing token and names the four labels.
 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`, `escalation_reminder` and
+8. `invalid`, `accepted`, `escalated`, `escalation_reminder` 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.
@@ -124,7 +153,7 @@ path that may read a 404 as absence.
 11. `setup` blocks on a `branch` the repository does not have, and names the
     repository's default branch when the config named none.
 12. An `escalated` comment says what a human can do from the issue, in this
-    tracker's gestures: add `readyLabel` to resume, close the issue to
+    tracker's gestures: add `resumeLabel` to resume, close the issue to
     abandon — and, for an escalation born in `merging`, only the first, since
     a close there is refused. An `escalation_reminder` is the same comment
     under "Still escalated": same diagnosis, same answers.
@@ -132,4 +161,11 @@ path that may read a 404 as absence.
     heading, one line saying it is the stopping step's own words written for
     the agent that repairs it, then the text fenced and folded at 80 columns.
 
-How to build and configure: [README.md](./README.md).
+14. A Feature is listed only with `featureReadyLabel`; its Tickets are its sub-issues;
+    a blocker read that fails is `unavailable`, never an empty list.
+15. `openLine` of an existing line succeeds; `settled` distinguishes a merge
+    from a close.
+16. `behind` is `current` at `behind_by` 0, `behind` with the count above it, and
+    `unavailable` when GitHub does not answer or the reference is not a pull request.
+
+How to build and configure: [README.md](./README.md).

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

@@ -1,11 +1,11 @@
 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 Kind = "create" | "update" | "resume" | "cancel" | "delete";
 export type IntentInput = {
     action: string | undefined;
     state: string | undefined;
     labels: string[];
-    readyLabel: string;
+    resumeLabel: string;
 };
 export type IntentResult = {
     ok: true;
@@ -19,7 +19,7 @@ export type IntentResult = {
  *
  * 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
+ * itself, closed means drop it. `resume` 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.
  */

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

@@ -1 +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"}
+{"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,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AA+BxE,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,WAAW,EAAE,MAAM,CAAC;CACrB,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

@@ -22,7 +22,7 @@ const ACTION_TO_KIND = {
 const KIND_TO_INTENT = {
     create: "upsert",
     update: "upsert",
-    ready: "ready",
+    resume: "resume",
     cancel: "cancel",
     delete: "cancel",
 };
@@ -31,7 +31,7 @@ const KIND_TO_INTENT = {
  *
  * 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
+ * itself, closed means drop it. `resume` 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.
  */
@@ -49,8 +49,8 @@ export function readIntent(input) {
             },
         };
     }
-    if (input.action === "labeled" && hasLabel(input.labels, input.readyLabel)) {
-        return { ok: true, intent: KIND_TO_INTENT.ready };
+    if (input.action === "labeled" && hasLabel(input.labels, input.resumeLabel)) {
+        return { ok: true, intent: KIND_TO_INTENT.resume };
     }
     return { ok: true, intent: KIND_TO_INTENT[kind] };
 }

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

@@ -1 +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"}
+{"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,MAAM,EAAE,QAAQ;IAChB,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,WAAW,CAAC,EAAE,CAAC;QAC5E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,CAAC;IACrD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;AACpD,CAAC"}

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

@@ -7,7 +7,11 @@ export type NormalizeOptions = {
     defaultPriority: number;
     projectLabelPrefix: string;
     priorityLabelPrefix: string;
-    readyLabel: string;
+    resumeLabel: string;
+    mergeWhenReadyLabel: string;
+    skipTestE2eLabel: string;
+    /** Keys of the issues that block this one, read beside it: the issue itself does not carry them. */
+    blockedBy?: string[];
     normalizedAt: string;
 };
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/adapter/normalize/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAA4B,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAMzF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAgGF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAmIpF"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/adapter/normalize/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAA4B,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAMzF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAgGF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA0IpF"}

package/dist/adapter/normalize/normalize.js

@@ -138,7 +138,7 @@ export function normalize(raw, options) {
         action: raw.action,
         state: state.value,
         labels: labels.names,
-        readyLabel: options.readyLabel,
+        resumeLabel: options.resumeLabel,
     });
     if (!intent.ok) {
         return { ok: false, invalid: intent.invalid };
@@ -206,6 +206,10 @@ export function normalize(raw, options) {
         ...(title.value !== undefined ? { title: title.value } : {}),
         ...(intention !== undefined ? { intention } : {}),
         priority: priority.value ?? options.defaultPriority,
+        blocked_by: options.blockedBy ?? [],
+        merge_when_ready: labels.names.some((name) => name.toLowerCase() === options.mergeWhenReadyLabel.toLowerCase()),
+        skip_e2e: options.skipTestE2eLabel.length > 0 &&
+            labels.names.some((name) => name.toLowerCase() === options.skipTestE2eLabel.toLowerCase()),
         ...(Object.keys(source).length > 0 ? { source } : {}),
         fingerprint: "",
         normalized_at: options.normalizedAt,