@detergent-software/conductor 1.4.0-dev.2 → 1.4.0-dev.4

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 Releases are tagged `conductor-v<version>` and staged on npm by `atk-conductor-release` (`pipelines/release-conductor.yml`), which writes each section below. `scripts/check-changelog.mjs` fails when a tag has no section here.
 
+## [1.4.0-dev.4](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTconductor-v1.4.0-dev.3&targetVersion=GTconductor-v1.4.0-dev.4) (2026-10-15)
+
+### Features
+
+* **conductor:** a GitHub Issues tracker kind (ATK-458) ([6028a13](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/6028a136cc39e1ed51072571629e68dead466d35))
+
+### Bug Fixes
+
+* **conductor:** review fixes for the github-issues tracker (ATK-458) ([79abe60](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/79abe602f80138714098a61821d16dfc015787c0))
+
+## [1.4.0-dev.3](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTconductor-v1.4.0-dev.2&targetVersion=GTconductor-v1.4.0-dev.3) (2026-10-15)
+
+### Features
+
+* **conductor:** a brief with the phase, the PR and the comments (ATK-456) ([cfd0f11](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/cfd0f11e8881f43eb0d4d4d4f93800738f81d57f))
+* **conductor:** conduct file, in-process notes and the PR reference (ATK-456) ([0b3311b](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/0b3311b7ec877cc7846d1c5607c35c653c43b58d))
+* **conductor:** phase notes move the tracker state (ATK-456) ([6c93b91](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/6c93b91fc7f0487c41ddfe357248a3bfdc97a463))
+
+### Bug Fixes
+
+* **conductor:** guard the brief found in review (ATK-456) ([5d7debe](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/5d7debe7cd670bc20798f7d55438bfc24d1095be))
+* **conductor:** guard the note and follow-up paths found in review (ATK-456) ([6d881da](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/6d881daca5d5c5103943fba6a1560f7ae4db36de)), closes [AB#12](https://emergentcode.visualstudio.com/Emergent%20Software/_workitems/edit/12)
+
+### Refactoring
+
+* **conductor:** the brief names its PR with the notes' helper (ATK-456) ([7b3f009](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/7b3f009715cce46a4ac02697bdca3680ab9f78f5))
+
 ## [1.4.0-dev.2](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTconductor-v1.4.0-dev.1&targetVersion=GTconductor-v1.4.0-dev.2) (2026-10-15)
 
 ### Features

package/README.md

@@ -104,18 +104,28 @@ Worker statuses: `launching`, `running`, `parked`, `stopped-unexpectedly`, `fail
 
 ## Notes
 
-A worker writes each phase note (`## <work skill> · <Phase>[ · <kind>: <one line>]`, such as `## work-issue · PR opened`) with `conduct note <item> <file>`. The daemon posts the file as a comment on the item in the tracker, then records the phase at once: on the worker (`phase` in `GET /fleet` and `conduct status`), on the item, and as a `note.posted` event. A PR opened note also records the worker's PR (`pr`, such as `ado:Emergent.AgenticToolkit#1850` or `github:<owner>/<repo>#458`) from its first PR link, replacing an earlier one; until then, the worker's first `pr:` wait records it. `conduct status` and the console's fleet pane show it. The worker is `--worker <worker>`, else the one whose worktree is the current checkout, else the project's live worker on that item. The project is the worker's, else the one whose tracker key (the Linear team, or the Boards `key`) is the item's key prefix.
+A worker writes each phase note (`## <work skill> · <Phase>[ · <kind>: <one line>]`, such as `## work-issue · PR opened`) with `conduct note <item> <file>`. The daemon posts the file as a comment on the item in the tracker, then records the phase at once: on the worker (`phase` in `GET /fleet` and `conduct status`), on the item, and as a `note.posted` event. A PR opened note also records the worker's PR (`pr`, such as `ado:Emergent.AgenticToolkit#1850` or `github:<owner>/<repo>#458`) from its first PR link, replacing an earlier one; until then, the worker's first `pr:` wait records it. `conduct status` and the console's fleet pane show it. The worker is `--worker <worker>`, else the one whose worktree is the current checkout, else the project's live worker on that item. The project is the worker's, else the one whose tracker key (the Linear team, or the Boards or GitHub Issues `key`) is the item's key prefix.
+
+**State follows the notes** (providers design note, section 5). A `Started`, `PR opened` or `Landed` note (not a Handoff) also moves the item, to the state its phase maps to in the profile's `tracker.transitions`:
+
+| Phase | Linear default | ADO Boards default (Scrum) | GitHub Issues default |
+|---|---|---|---|
+| `started` | In Progress, assigned to the key's owner | Committed, assigned to the `az` identity | the label `in-progress`, assigned to the gh account |
+| `pr-opened` | In Review, the PR attached | no change, the PR linked (an `ArtifactLink` for an ADO PR, a `Hyperlink` for a GitHub one) | the label `in-review` in place of `in-progress`; a GitHub PR is linked by the `Refs <owner>/<repo>#<n>` its body carries, any other by a comment with its URL |
+| `landed` | Done | Done | closed as completed, the phase label taken off |
+
+A phase mapped to `null` moves nothing (`started` still assigns). A `Started` never reopens a closed item (`kept`); a `PR opened` on one does, for a follow-up PR. The PR linked is the worker's, else the note's first PR link. A write the tracker refuses is a warning on the note's answer and stderr, and a `tracker.transition-failed` event; the note stands, and the verb still exits 0. A write that took is `tracker.transitioned`. With no daemon, `conduct note` posts from the item's project checkout as its account, and moves the item the same way; nothing is recorded then.
 
 The work skill is the profile's `skills.work`. A note headed with one of `skills.aliases` counts the same, there and wherever the daemon reads notes (approvals, `conduct wait item … note`, the review-thread checks of `conduct wait pr … comment`). So when a project renames its work skill (ATK's `work-issue` became `work-item`), the old name goes in `aliases` and items in flight keep their phases.
 
 | Exit | Means | The worker then |
 |---|---|---|
 | 0 | posted | goes on |
-| 3 | nobody posted it: no daemon, one without notes, or the tracker refused it (such as a read-only key) | posts the note to the tracker itself, as before protocol v1 |
+| 3 | nobody posted it: the tracker refused it (such as a read-only key), or no daemon and this isn't the item's project checkout | posts the note to the tracker itself, as before protocol v1 |
 | 4 | not posted: Jason wrote `revise: …` after the item's newest Plan was approved, by him (a comment, `conduct approve`, the worker's tab) or by the conductor (`auto-approve now`, see Rules); stdout has his words | stops, re-plans with them, posts a new Plan and waits for approval, which the gate now holds |
 | 1 | refused (no heading, no project) or unclear (the daemon or Linear didn't answer the write) | reads the message; when it says the note may be there, looks before posting again |
 
-On Linear the daemon uses the key the watchers read (below), so that key needs **Create comments** as well as Read. Comments it writes carry the key owner's name, as the Linear MCP's do. On ADO Boards it posts a markdown discussion comment as the `az login` identity.
+On Linear the daemon uses the key the watchers read (below), so that key needs **Create comments** as well as Read. Comments it writes carry the key owner's name, as the Linear MCP's do. On ADO Boards it posts a markdown discussion comment as the `az login` identity, and on GitHub Issues an issue comment as the project's gh account.
 
 ## Briefs
 
@@ -123,20 +133,23 @@ On Linear the daemon uses the key the watchers read (below), so that key needs *
 - the title, URL, status (name and type), the tracker's project, Area and labels;
 - the blockers, the items it blocks and the related items, each with its status and title;
 - its phase notes (time, phase, kind and line), the newest Plan, and the `approve` / `revise:` after it with its words;
+- the work skill's `phase`: `orient`, `plan`, `awaiting-approval`, `implement`, `wait`, `land`, `done`, `abandoned` or `canceled`, from the status, the notes and the PR;
+- the `pr`: its worker's, else the newest `PR opened` note's link, read on the project's code host, with its state and verdict (or why it couldn't be read);
 - the description.
 
-`--json` prints it as one object.
+`--json` prints it as one object. `--comments` adds every comment's words, time, and whether the key's owner wrote it. With no daemon it is read here, from the item's project checkout as its account.
 
 The queue's snapshot has no descriptions, relations or comments, so the daemon reads the item itself:
 - **Linear:** one GraphQL request with the watchers' key, and more only for comments past the first 100.
 - **ADO Boards:** the work item with its links, its linked items' titles and states, its discussion comments and the `az login` identity. Predecessor is a blocker, Successor an item it blocks.
+- **GitHub Issues:** the issue, its comments, the issues it is blocked by and blocks (GitHub's issue dependencies; one in another repo is `<owner>/<repo>#<n>`) and the gh account's login. GitHub has no related relation, so the brief lists none.
 
 A brief is kept for 30 seconds. Anything the daemon sees happen to the item drops it: a note it posted, an `approve` or `revise` it posted, a wait resolved. `--fresh` reads the tracker again, as a worker checking for an approval after a wake should.
 
 | Exit | Means | The worker then |
 |---|---|---|
 | 0 | the brief | uses it |
-| 3 | no daemon, one without the brief API, or one that couldn't read the tracker (no key, the tracker down) | reads the item from the tracker itself (the Linear MCP, or the work skill's helper) |
+| 3 | no daemon and this isn't the item's project checkout, or the tracker couldn't be read (no key, the tracker down) | reads the item from the tracker itself (the Linear MCP, or the work skill's helper) |
 | 1 | refused: no project tracks the item, or the tracker has no such item | reads the message |
 
 ## Worker verbs
@@ -147,6 +160,8 @@ Protocol 2's verbs on git and the code host (providers design note, section 4),
 - `conduct pr create` checks everything before it pushes, `--dry-run` included: the title carries the item key, the branch carries it too and isn't the base, the description fits the host (ADO 4,000 characters, GitHub 65,536), no PR is open from the branch yet, nothing is uncommitted, the branch is ahead of its base, and commitlint passes (skipped in a clone without it installed, whose own CI lints the PR). Then it pushes from the checkout and has the daemon open the PR (`POST /workers/:id/prs`). The daemon checks ownership again from its own records and the worktree, never from the request: the worker is live, the branch the worktree is on now (or the `--repo` checkout's) carries the worker's item, and the title carries it. It records the PR on the worker (`pr`; another repo's only while the worker has none) and logs `code-host.pr-created`. `conduct branch` renames only the item's own branch, never the base, `main` or another item's.
 - `conduct land <pr>` sets the worker's PR up to land, as the helper's `land` did, and is safe to repeat. The PR must be the worker's (the same checks, and from the branch the checkout is on now, into its base). A brake already on it (a comment, a failed build, conflicts) is reported, and nothing is armed. A Landing note whose landing armed something, with that gone now, means someone cancelled it: `auto-merge-cancelled`, until `--rearm`. `--mode` is held to the profile's landing rules (`work.landing`) for the PR's files as pushed (`origin/<base>...origin/<head>`, fetched first) and the plan's tier. The daemon reads the tier from the item's Plan note; in-process it takes `--tier`, and auto is refused without one. Without `--mode` the rules pick it. Then it arms the host's own landing behind its capability check (`landingCheck`). On ADO that is a +10 vote in auto mode, with auto-complete and noFastForward. On GitHub it is auto-merge with a merge commit in auto mode, where the repo allows it; in review mode nothing is armed. It posts the Landing note last, and a new one whenever the mode changes, then prints the verdict. A failed build comes with its log, and a merge with whether it has two parents. The daemon logs `code-host.landing-armed` with the mode.
 - `conduct wait pr <pr>` (no event word) is the verdict wait, `pr:<host>:<repo>#<n>:verdict`: it holds on the first verdict that isn't `waiting`, with a line such as `pr 2030 build-failed: <pipeline>`. While it waits on a PR whose landing the daemon recorded, the ADO watcher keeps it armed. It queues an expired build again (once per wait) and, in auto mode, restores a cleared vote (never over a negative one), logged as `code-host.kept-armed`. A local wait (no daemon) gives the same verdicts but keeps nothing armed.
+- `conduct pr create` ends the description with the tracker's reference when it has one, before the length check: `AB#<id>` for an ADO Boards item on a GitHub PR, so the Boards GitHub app links it, and `Refs <owner>/<repo>#<n>` for a GitHub Issues item on a GitHub PR. Linear has none.
+- `conduct file --title … --body-file … --area … [--related …] [--blocked-by …] [--human]` files a follow-up of the checkout's item: in Backlog, in the item's project, with one Area (a label of the profile's Area group, a path below a board's `areaRoot`, or the name after a GitHub Issues `areaPrefix` label), the profile's `triageLabel`, and its `humanLabel` with `--human`. It is related to the item and each `--related`, and waits on each `--blocked-by` (keys, repeated or comma-separated). A key of another project, or an Area outside the group, is refused before anything is written. On Linear a relation that fails after the issue exists is a warning; on Boards the item and its links are one request. On GitHub Issues the follow-up also carries the `queueLabel`, the related items are a `Related: #n` line in its body (GitHub has no related relation), and a dependency that fails after the issue exists is a warning. The daemon files it for the worker (`POST /workers/:id/follow-ups`) and logs `tracker.filed`. The worker searches for a duplicate first, with the tracker's own tools: this only files.
 - `conduct pr threads <pr>` lists the PR's threads (on GitHub each comment and review) with `needsAnswer` (ATK-384). `conduct reply <pr> [<thread>]` answers on the worker's own PR: in the ADO thread named, or as a note on the PR. The text is headed `## <work skill> · Reply` unless it starts with a note heading. The daemon logs `code-host.replied`. `--repo` takes `github:<owner>/<repo>` (from its `.scratch/repos` checkout, into its default branch) or `ado:<repository>`; the profile's `codeHost` is the default.
 - `conduct runs <sha>` is one look at a merge's runs, as the helper's `runs-watch --once` and `stage` were (ATK-455). It is a read, so it always runs here.
   - **Which runs.** On Azure Pipelines (the profile's `ci: ado-pipelines`, for its Azure DevOps repo), they are the pipelines whose YAML trigger the merge fires. The YAML and the merge's changed files are read in the worktree, which fetches the base when it hasn't got the commit. On GitHub Actions (`--repo github:<owner>/<repo>`, or `ci: github-actions` for a GitHub repo), they are the runs the merge's push started.
@@ -161,7 +176,9 @@ Every write the conductor makes outside its own store, with what triggers it and
 
 | Write | Trigger | Identity |
 |---|---|---|
-| A phase note on the item | `conduct note` (a worker) | the Linear key's owner; on Boards, the project's `az` identity |
+| A phase note on the item | `conduct note` (a worker) | the Linear key's owner; on Boards, the project's `az` identity; on GitHub Issues, its gh account |
+| The item's state, its assignee on `started`, and the PR's link (see Notes) | a `Started`, `PR opened` or `Landed` note | the Linear key's owner, the `az` identity, or the gh account |
+| A follow-up item and its relations | `conduct file` → `POST /workers/:id/follow-ups` | the Linear key's owner, the `az` identity, or the gh account |
 | `approve` / `revise:` on the item | `conduct approve` / `revise`, the console | the Linear key's owner, or the `az` identity |
 | An auto-approval comment | a rule's `auto-approve now` / `after` | the Linear key's owner, or the `az` identity |
 | A label added or removed (`human`, `triage`, `shipped-open`) | a rule's `label add` / `remove` | the Linear key's owner, or the `az` identity (a tag) |
@@ -172,7 +189,7 @@ Every write the conductor makes outside its own store, with what triggers it and
 | A reply on the worker's PR | `conduct reply` → `POST /workers/:id/replies` | the project's `az` identity, or its gh account |
 | A train: its branch, the members' merges into it, its PR, a note on each member | `conduct train` (you) | the project's gh account |
 
-Accounts are per project (see Accounts). Each code-host write is an event: `code-host.pr-created`, `code-host.landing-armed`, `code-host.kept-armed`, `code-host.replied`.
+Accounts are per project (see Accounts). Each code-host write is an event: `code-host.pr-created`, `code-host.landing-armed`, `code-host.kept-armed`, `code-host.replied`. So is each tracker write a worker causes: `tracker.transitioned` (or `tracker.transition-failed`) and `tracker.filed`. Rules still never change an item's state: only its phase notes do.
 
 ## Inbox
 
@@ -363,8 +380,8 @@ A worker waits by posting its note, running `conduct wait …` and ending the tu
 | `run atk-api-deploy 12345 done` | `run:ado:atk-api-deploy#12345:done` | the run completed, with its result |
 | `npm 8.5.0-dev.2 --tag dev` | `npm:@detergent-software/atk@8.5.0-dev.2:dev` | the dist-tag points at the version, read through the `npm-stage` release adapter |
 | `health dev --version 1.2.3` / `--commit <sha>` | `health:dev:version=1.2.3` | the profile's `health.dev` URL answers with that version or commit |
-| `approval` | `approval:linear:ATK-310` (`approval:ado-boards:CAD-12` on Boards) | an `approve` / `revise:` comment by the Linear key's owner (on Boards, the `az login` identity) after the item's newest `<work skill> · Plan` note |
-| `item ATK-271 done` / `label human` / `note Landed` | `item:linear:ATK-271:state=done` | the state (name or type), a label (a tag on Boards), or a phase note |
+| `approval` | `approval:linear:ATK-310` (`approval:ado-boards:CAD-12` on Boards, `approval:github-issues:PAR-12` on GitHub Issues) | an `approve` / `revise:` comment by the Linear key's owner (on Boards, the `az login` identity; on GitHub Issues, the gh account) after the item's newest `<work skill> · Plan` note |
+| `item ATK-271 done` / `label human` / `note Landed` | `item:linear:ATK-271:state=done` | the state (name or type), a label (a tag on Boards), or a phase note; on GitHub Issues the state is `open`, `closed`, a phase label or its type |
 | `login ado` / `github` / `linear` | `login:ado:atk` | the project's login to the provider works again: a probe as its account (see Accounts) succeeds |
 | `time 2026-10-10T09:00` | `time:2026-10-10T14:00:00.000Z` | the time has passed (no zone means local time) |
 
@@ -433,6 +450,37 @@ A project whose work items live in Azure DevOps Boards (Cadence) sets `tracker.k
 
 Everything goes through the project's `az` token (see Accounts). The reads (the scheduler's queue and the watchers' waits) take from the `ado` watcher's budget, as PR and pipeline waits do. A wait pass reads every waited item of a board in one batch, and an item's comments only when its rev or comment count moved. Notes and the rules' `label` edits (a patch of `System.Tags` alone, refused if the item changed since it was read) are writes, outside the budget, as on Linear.
 
+## GitHub Issues
+
+A project whose items are a GitHub repo's issues sets `tracker.kind` to `github-issues` (providers design note, section 5; ATK-458):
+
+```jsonc
+"tracker": {
+  "kind": "github-issues",
+  "key": "PAR",              // items are PAR-<issue number>: issue numbers are numbers alone
+  "humanLabel": "human",     // a label
+  "triageLabel": "triage",   // optional, a label too: new items Jason hasn't triaged (see Scheduler)
+  "queueLabel": "conduct",   // the default: the open issues carrying it are the queue
+  "areaPrefix": "area:",     // the default: area:docs is the Area docs
+  "priority": 3,             // the queue's priority against other projects' (1 urgent … 4 low)
+  "transitions": { "started": "in-progress", "pr-opened": "in-review" } // the defaults
+  // "owner", "repo": the GitHub code host's by default; required beside an Azure DevOps one
+}
+```
+
+| Tracker concept | On GitHub Issues |
+|---|---|
+| the queue | the open issues labelled `queueLabel`, oldest first, one tracker project named after the repo with the profile's `priority`. PRs, which the issues API lists too, are left out. In-flight issues are read as well, so a closed one retires its worker. |
+| Area | the name after `areaPrefix` on the issue's first such label |
+| blockers | GitHub's issue dependencies (`blocked by`) still open, inside the queue or not; one in another repo is listed as `<owner>/<repo>#<n>` |
+| human, triage, labels | labels, matched in any case |
+| states | open → unstarted; open with a `transitions` label → started (named after the label); closed as completed → completed; closed as not planned or a duplicate → canceled |
+| phase notes, `approve` / `revise:` | issue comments; the gh account's own comments count as Jason's, so the note heading tells them apart |
+
+`Closes #n` would close an issue only on a merge to the default branch, so the conductor closes it on the `Landed` note instead, and a project on a `develop` branch works the same. Phase labels are added and taken off one at a time, never replaced as a set, so a label someone else added meanwhile stays. GitHub makes a label it doesn't have yet when a phase or rule first adds it; `conduct file` refuses an Area with no label.
+
+Everything goes through the project's gh account (`projects.<name>.github.user`, else gh's active account; see Accounts). The reads (the scheduler's queue and the watchers' waits) take from the `github` watcher's budget, as PR and merge waits on GitHub do. A wait pass reads each waited issue once, and its comments only when its update time or comment count moved. Notes, label edits and the tracker writes are outside the budget, as on Linear. That account's rate limit is shared with anything else it runs (ATK's prod API reads with Jason's), so the `github` watcher's `perMinute` bounds it.
+
 ## Broker
 
 The broker shares what every project on the machine uses (ATK-318).

package/build/brief-cli.js

@@ -1,70 +1,152 @@
 import { z } from 'zod';
-import { briefLines } from "./brief.js";
+import { BriefError, briefLines, briefOf, briefPrs, linearBriefs, notedPr, } from "./brief.js";
 import { callApi, NotRunningError } from "./client.js";
+import { projectHosts } from "./code-host.js";
+import {} from "./credentials.js";
 import { ConductorError } from "./errors.js";
-// Exit code for a brief no conductor gave (none running, one without the brief API, or one that
-// couldn't read the tracker): the worker reads the item from the tracker itself. A refusal (no
-// project tracks the item, the tracker has no such item) exits 1.
+import { checkoutProject, localCredentials } from "./in-process.js";
+import { ITEM } from "./notes.js";
+import { notePrefixes } from "./profile.js";
+import { routedBriefs } from "./trackers.js";
+import { boardsBriefs } from "./watchers/boards-brief.js";
+import { issuesBriefs } from "./watchers/issues-brief.js";
+// Exit code for a brief nobody gave (no conductor answered, and this isn't the item's project
+// checkout to read it from; or the conductor couldn't read the tracker): the worker reads the item
+// from the tracker itself. A refusal (no project tracks the item, the tracker has no such item)
+// exits 1.
 export const NOT_BRIEFED = 3;
-// The daemon asks the tracker once or a few times, each within 20 s.
-const BRIEF_TIMEOUT_MS = 60_000;
+// The daemon asks the tracker once or a few times, and the code host for the PR, each within 20 s.
+const BRIEF_TIMEOUT_MS = 90_000;
 const link = z.object({ id: z.string(), status: z.string().nullable(), title: z.string().nullable() });
 export const briefSchema = z.object({
     approval: z.object({ at: z.string(), kind: z.enum(['approve', 'revise']), text: z.string() }).nullable(),
     area: z.string().nullable(),
     blockedBy: z.array(link),
     blocks: z.array(link),
+    comments: z.array(z.object({ at: z.string(), body: z.string(), byViewer: z.boolean() })),
     description: z.string(),
     item: z.string(),
     labels: z.array(z.string()),
     notes: z.array(z.object({ at: z.string(), kind: z.string().nullable(), line: z.string().nullable(), phase: z.string() })),
+    phase: z.enum(['abandoned', 'awaiting-approval', 'canceled', 'done', 'implement', 'land', 'orient', 'plan', 'wait']),
     plan: z.string().nullable(),
+    pr: z
+        .object({
+        error: z.string().optional(),
+        outcome: z
+            .enum([
+            'abandoned',
+            'auto-merge-cancelled',
+            'build-failed',
+            'changes-requested',
+            'conflicts',
+            'merge-failed',
+            'merged',
+            'review-comment',
+            'waiting',
+        ])
+            .nullable(),
+        ref: z.string(),
+        state: z.enum(['closed', 'merged', 'open']).nullable(),
+        title: z.string().nullable(),
+        url: z.string().nullable(),
+    })
+        .nullable(),
     project: z.string(),
     readAt: z.string(),
     related: z.array(link),
-    // A daemon from before it gives none.
-    revise: z.object({ at: z.string(), text: z.string() }).nullable().default(null),
+    revise: z.object({ at: z.string(), text: z.string() }).nullable(),
     status: z.object({ name: z.string(), type: z.string().nullable() }),
     title: z.string(),
     trackerProject: z.string().nullable(),
     url: z.string().nullable(),
 });
 const refused = z.object({ details: z.array(z.string()).optional(), error: z.string() });
-// `conduct brief <item>`: the item's context from the daemon, as text or JSON. Returns the exit
-// code: 0, NOT_BRIEFED, or 1 (thrown) when the conductor refused it.
+// `conduct brief <item>`: the item's context, as text or JSON; its comments with --comments. From
+// the daemon, else read here from this checkout's project. Returns the exit code: 0, NOT_BRIEFED,
+// or 1 (thrown) when it was refused.
 export async function briefCommand(paths, item, options, io) {
-    const notBriefed = (why) => {
-        io.err(`no brief: ${why}; read the item from the tracker yourself`);
-        return NOT_BRIEFED;
-    };
     let answer;
     try {
         answer = await callApi(paths, {
             method: 'GET',
-            path: `/items/${encodeURIComponent(item)}/brief${options.fresh ? '?fresh=true' : ''}`,
+            path: `/items/${encodeURIComponent(item)}/brief?${new URLSearchParams({
+                ...(options.fresh ? { fresh: 'true' } : {}),
+                ...(options.comments ? { comments: 'true' } : {}),
+            }).toString()}`,
             timeoutMs: BRIEF_TIMEOUT_MS,
         });
     }
     catch (error) {
         if (error instanceof NotRunningError)
-            return notBriefed('the conductor is not running');
+            return briefHere(paths, item, options, io, 'the conductor is not running');
         throw error;
     }
     if (answer.status === 200) {
-        const { brief } = z.object({ brief: briefSchema }).parse(answer.body);
-        if (options.json)
-            io.out(JSON.stringify(brief, null, 2));
-        else
-            briefLines(brief).forEach((line) => io.out(line));
+        const given = z.object({ brief: briefSchema }).safeParse(answer.body);
+        // A conductor of another version gives a brief of another shape: read it here instead.
+        if (!given.success)
+            return briefHere(paths, item, options, io, "this conductor's brief is of another version");
+        print(given.data.brief, options, io);
         return 0;
     }
     const error = refused.safeParse(answer.body).data;
     // A daemon from before the brief API answers its route's `not_found`; a missing item says which.
     if (answer.status === 404 && error?.error === 'not_found')
-        return notBriefed('this conductor has no brief API (upgrade it)');
+        return briefHere(paths, item, options, io, 'this conductor has no brief API');
     // The conductor couldn't read the tracker (no key, the tracker down): the worker still may.
     if (answer.status === 502)
-        return notBriefed(`${error?.error ?? 'the conductor could not read the tracker'}${error?.details?.length ? ` (${error.details.join('; ')})` : ''}`);
+        return notBriefed(io, `${error?.error ?? 'the conductor could not read the tracker'}${error?.details?.length ? ` (${error.details.join('; ')})` : ''}`);
     throw new ConductorError(error?.error ?? `the API answered ${answer.status}`, error?.details ?? []);
 }
+// The brief read here, with no conductor: the tracker and the PR as this checkout's project's
+// account. Without a daemon there is no worker, so the PR is the newest PR opened note's.
+async function briefHere(paths, item, options, io, why) {
+    if (!ITEM.test(item))
+        throw new ConductorError(`"${item}" is not a tracker item, such as ATK-311`);
+    const key = item.toUpperCase();
+    const here = await checkoutProject(io.cwd, key, why, 'read it from');
+    if ('refusal' in here)
+        return notBriefed(io, here.refusal);
+    const { profile } = here;
+    // The machine's accounts, built once, and only where a seam doesn't stand in for them. A config
+    // that can't be read is a brief that couldn't be read here (exit 3), as a tracker that is down.
+    let credentials;
+    const accounts = () => (credentials ??= localCredentials(paths));
+    // A PR it can't read (the accounts included) is an `error` on the brief, never a throw.
+    const prs = io.prs ?? briefPrs((project) => projectHosts(accounts(), project));
+    let read;
+    try {
+        const reader = io.reader ??
+            routedBriefs({
+                'ado-boards': boardsBriefs({ credentials: accounts() }),
+                'github-issues': issuesBriefs({ credentials: accounts() }),
+                linear: linearBriefs({ credentials: accounts() }),
+            });
+        read = await reader.read(key, profile);
+    }
+    catch (error) {
+        if (error instanceof BriefError && error.reason === 'missing')
+            throw new ConductorError(error.message);
+        return notBriefed(io, error instanceof Error ? error.message : String(error));
+    }
+    const prefixes = notePrefixes(profile);
+    const ref = notedPr(read.comments, prefixes);
+    const brief = briefOf(key, profile.name, read, prefixes, new Date(), ref === null ? null : await prs(profile, ref));
+    io.err(`read here (${why})`);
+    print(brief, options, io);
+    return 0;
+}
+function notBriefed(io, why) {
+    io.err(`no brief: ${why}; read the item from the tracker yourself`);
+    return NOT_BRIEFED;
+}
+function print(brief, options, io) {
+    if (options.json) {
+        const { comments: _comments, ...rest } = brief;
+        io.out(JSON.stringify(options.comments ? brief : rest, null, 2));
+    }
+    else
+        briefLines(brief, { comments: options.comments === true }).forEach((line) => io.out(line));
+}
 //# sourceMappingURL=brief-cli.js.map

package/build/brief-cli.js.map

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

package/build/brief.js

@@ -1,8 +1,10 @@
 import { z } from 'zod';
 import { ConductorError } from "./errors.js";
-import { noteHeading } from "./lib/providers/index.js";
-import { ITEM, projectFor } from "./notes.js";
+import { noteHeading, prVerdict } from "./lib/providers/index.js";
+import { firstPr, ITEM, projectFor } from "./notes.js";
 import { notePrefixes } from "./profile.js";
+import { ACTIVE_STATUSES } from "./store.js";
+import { linkedPr } from "./tracker-writes.js";
 import { linearApi, LinearRequestError } from "./watchers/linear-api.js";
 import { approvalAfterPlan } from "./watchers/linear.js";
 // `conduct brief` (design note, section 13): one item's context for a worker's orient step, read
@@ -18,8 +20,8 @@ export class BriefError extends ConductorError {
         this.reason = reason;
     }
 }
-// The brief as a reader sees it, for `conduct brief` without --json.
-export function briefLines(brief) {
+// The brief as a reader sees it, for `conduct brief` without --json; its comments with `comments`.
+export function briefLines(brief, { comments = false } = {}) {
     const links = (label, list) => list.length === 0
         ? []
         : [`${label}:`, ...list.map((l) => `  ${l.id}  ${l.status ?? '?'}  ${l.title ?? ''}`.trimEnd())];
@@ -28,10 +30,18 @@ export function briefLines(brief) {
         : brief.approval === null
             ? `none after the Plan of ${brief.plan}`
             : `${brief.approval.kind} ${brief.approval.at}: "${brief.approval.text}"`;
+    const { pr } = brief;
+    const prLine = pr === null
+        ? 'pr: none'
+        : pr.error !== undefined
+            ? `pr: ${pr.ref}  unread: ${pr.error}`
+            : `pr: ${pr.ref}  ${pr.state ?? '?'}  ${pr.outcome ?? '?'}${pr.url ? `  ${pr.url}` : ''}`;
     return [
         `${brief.item}  ${brief.title}`,
         ...(brief.url ? [brief.url] : []),
         `status: ${brief.status.name}${brief.status.type && brief.status.type !== brief.status.name.toLowerCase() ? ` (${brief.status.type})` : ''}`,
+        `phase: ${brief.phase}`,
+        prLine,
         `project: ${brief.project}${brief.trackerProject ? ` · ${brief.trackerProject}` : ''}`,
         `area: ${brief.area ?? 'none'}`,
         `labels: ${brief.labels.length > 0 ? brief.labels.join(', ') : 'none'}`,
@@ -48,11 +58,24 @@ export function briefLines(brief) {
         ...(brief.revise ? [`revised after it: ${brief.revise.at}: "${brief.revise.text}"`] : []),
         '',
         brief.description.trim() || '(no description)',
+        ...(comments
+            ? [
+                '',
+                brief.comments.length === 0 ? 'comments: none' : 'comments:',
+                ...brief.comments.flatMap((c) => [
+                    `  ${c.at}  ${c.byViewer ? 'the key owner' : 'someone else'}`,
+                    ...c.body
+                        .trim()
+                        .split(/\r?\n/)
+                        .map((line) => `    ${line}`.trimEnd()),
+                ]),
+            ]
+            : []),
     ];
 }
 // The brief from what the tracker gave: the comments as phase notes, the newest Plan, and the
 // approval after it.
-export function briefOf(item, project, read, prefixes, at) {
+export function briefOf(item, project, read, prefixes, at, pr = null) {
     const { comments, viewer, ...fields } = read;
     const sorted = [...comments].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt));
     const notes = sorted.flatMap((c) => {
@@ -74,18 +97,78 @@ export function briefOf(item, project, read, prefixes, at) {
     const revised = answers
         .slice(answers.findLastIndex((c) => /^approved?\b/i.test(c.body.trim())) + 1)
         .find((c) => /^revise\s*:/i.test(c.body.trim()));
+    const approval = found ? { ...found, text: said ? said.body.trim() : '' } : null;
+    const revise = revised ? { at: revised.createdAt, text: revised.body.trim() } : null;
     return {
         ...fields,
-        approval: found ? { ...found, text: said ? said.body.trim() : '' } : null,
+        approval,
+        comments: sorted.map((c) => ({
+            at: c.createdAt,
+            body: c.body,
+            byViewer: viewer !== null && c.authorId === viewer,
+        })),
         item,
         notes,
+        phase: briefPhase(fields.status, notes, { approval, revise }, pr),
         plan: notes.findLast((n) => n.phase === 'Plan')?.at ?? null,
+        pr,
         project,
         readAt: at.toISOString(),
-        revise: revised ? { at: revised.createdAt, text: revised.body.trim() } : null,
+        revise,
     };
 }
-export function briefService({ now = () => new Date(), reader, store, ttlMs = TTL_MS, }) {
+// The work skill's phase for an item: done or canceled by its status; then by its PR (open, merged,
+// abandoned, or one that couldn't be read, which still waits); not started; then by its newest
+// Plan: a `revise:` newer than its approval sends it back to plan, an approval (a `Plan approved`
+// note or Jason's `approve`) to implement, and no answer yet waits.
+export function briefPhase(status, notes, answers, pr) {
+    if (status.type === 'completed')
+        return 'done';
+    if (status.type === 'canceled')
+        return 'canceled';
+    if (pr?.state === 'merged')
+        return 'land';
+    if (pr?.state === 'closed')
+        return 'abandoned';
+    if (pr !== null)
+        return 'wait';
+    if (status.type === 'backlog' || status.type === 'unstarted' || status.type === 'triage')
+        return 'orient';
+    const plan = notes.findLast((n) => n.phase === 'Plan');
+    if (!plan)
+        return 'plan';
+    const { approval, revise } = answers;
+    const noted = notes.findLast((n) => n.phase === 'Plan approved' && Date.parse(n.at) > Date.parse(plan.at));
+    const approvedAt = Math.max(noted ? Date.parse(noted.at) : -Infinity, approval?.kind === 'approve' ? Date.parse(approval.at) : -Infinity);
+    const revisedAt = Math.max(revise ? Date.parse(revise.at) : -Infinity, approval?.kind === 'revise' ? Date.parse(approval.at) : -Infinity);
+    if (revisedAt > approvedAt)
+        return 'plan';
+    return approvedAt > -Infinity ? 'implement' : 'awaiting-approval';
+}
+// The PR reader of the projects' code hosts: the PR as the host has it, with its verdict.
+export function briefPrs(hosts) {
+    return async (profile, ref) => {
+        const link = linkedPr(ref, profile);
+        const unread = (error) => ({
+            error,
+            outcome: null,
+            ref,
+            state: null,
+            title: null,
+            url: link?.url ?? null,
+        });
+        if (link === null)
+            return unread(`${ref} isn't a PR ${profile.name}'s code host reads`);
+        try {
+            const pr = await hosts(profile.name)(link.repo).read(link.number, { notePrefixes: notePrefixes(profile) });
+            return { outcome: prVerdict(pr).outcome, ref, state: pr.state, title: pr.title, url: pr.url };
+        }
+        catch (error) {
+            return unread(error instanceof Error ? error.message : String(error));
+        }
+    };
+}
+export function briefService({ now = () => new Date(), prs, reader, store, ttlMs = TTL_MS, }) {
     const cache = new Map();
     // Bumped by each event about an item, so a read that began before one isn't kept.
     const changes = new Map();
@@ -129,13 +212,28 @@ export function briefService({ now = () => new Date(), reader, store, ttlMs = TT
                 const details = error instanceof ConductorError ? error.details : [];
                 throw new BriefError(`couldn't read ${key}: ${error instanceof Error ? error.message : String(error)}`, 'unreadable', details);
             }
-            const brief = briefOf(key, project.name, read, notePrefixes(project.profile), now());
+            const prefixes = notePrefixes(project.profile);
+            // The PR its live worker has, else the one its newest PR opened note links.
+            const recorded = store
+                .listWorkers(ACTIVE_STATUSES)
+                .find((w) => !w.probe && w.project === project.name && w.item.toUpperCase() === key)?.pr;
+            const ref = recorded ?? notedPr(read.comments, prefixes);
+            const pr = prs && ref ? await prs(project.profile, ref) : null;
+            const brief = briefOf(key, project.name, read, prefixes, now(), pr);
             if ((changes.get(key) ?? 0) === seen)
                 cache.set(key, { at: now().getTime(), brief });
             return brief;
         },
     };
 }
+// The PR the newest PR opened note links, as a worker's `pr`; null without one.
+export function notedPr(comments, prefixes) {
+    const opened = [...comments]
+        .sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+        .filter((c) => noteHeading(c.body, prefixes)?.phase === 'PR opened')
+        .at(-1);
+    return firstPr(opened?.body ?? '');
+}
 const STATE = 'state { name type }';
 const LINKED = `identifier title ${STATE}`;
 const COMMENTS = 'comments(first: 100, after: $after) { pageInfo { hasNextPage endCursor } nodes { body createdAt user { id } } }';