squad-kit 1.3.19 → 1.3.21

package/dist/console-ui/index.html

@@ -7,8 +7,8 @@
     <link rel="icon" href="/favicon.ico" sizes="any" />
     <link rel="icon" href="/logo.svg" type="image/svg+xml" />
     <title>squad-kit board</title>
-    <script type="module" crossorigin src="/assets/index-Cn6JuFKc.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DVTP7K3b.css">
+    <script type="module" crossorigin src="/assets/index-DRUpnlyX.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DwynFGnn.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/console.md

@@ -100,8 +100,8 @@ On the board:
   on this project, and a step bar. A ticket over the limit of tickets at once says "Next in line: starts when a
   slot is free". A slow step says "Taking longer than usual".
 - **All tickets**, **Mine** and **Bugs** filter the cards. **Search tickets** finds one.
-- **New ticket** writes a ticket in plain words. **Pull from Azure DevOps** brings in a work item (or
-  **Connect a tracker**, when there is none). Under the track (Full or Express), **Write new tests** is on by default.
+- **New ticket** writes a ticket in plain words. **Pull from** your tracker (Azure DevOps or GitHub) brings in an item
+  (or **Connect a tracker**, when there is none). Under the track (Full or Express), **Write new tests** is on by default.
   Turn it off for a demo, a small text or colour change, or a project with no tests yet: the plan and the Builder add no
   new tests and the Reviewer does not ask for them, while squad-kit still runs your project's own checks (tests, lint,
   build), the review and the proof, so a break of what already works still shows. The story then says **Built without new
@@ -357,6 +357,78 @@ REST (under `/p/<project>/api/v1`):
 | `POST /tickets/<id>/review/past` | `{ "note": 3, "reason": "…" }`: go past one open note, before Looks right. A reason is a must. Answers with the review. |
 | `POST /tickets/<id>/review/write` | Write the review into the story's merged pull request again: only the threads that are missing. Refused on a pull request that is not merged or was closed. Answers `{ "ok", "pr", "threads", "why" }`. |
 
+## Pull requests on GitHub
+
+squad-kit opens pull requests on GitHub through GitHub's own tool, **gh**, signed in as you (`gh auth login`). It asks
+gh for the sign-in each time and keeps no token; `git push` signs in through gh too, for that push only. Without gh, or
+with gh not signed in, nothing changes from before: the work merges on your computer. The **Tools** page has a line for
+gh, Recommended for a project kept on GitHub, with the steps.
+
+**Your own repo, a fork too.** A fork is your team's own repo: its pull requests stay in it. Looks right pushes the
+story's branch, opens the pull request into main, and merges it with a merge commit when GitHub allows it; the branch
+goes, and your own main follows. squad-kit never waits for that in the step: while GitHub's checks run, a branch rule
+waits for a person's approval, or GitHub could not be reached just then (a laptop waking from sleep), the story says
+"Waits on the code host: its checks or an approval", and squad-kit looks again every few minutes and merges it then (or
+at once with **Check again**, which also merges one that stopped once it can). A failed check, a draft or a clash is said
+plainly on the story, and squad-kit never goes around a rule. Closed on GitHub while it waits, the story says so, with
+**Send it again** and **Leave it closed**. A release never starts while one of its pull requests still waits; on a main
+that only takes pull requests, the release goes through its own pull request and waits up to 10 minutes for its checks. A branch rule that wants the newest main brings it in on
+GitHub once. When you can't push to the repo, the story merges on this computer instead, as with no code host, and says
+why. The review goes in after the merge: each note a comment on its file and line, fixed ones resolved, and one comment
+for who pressed Looks right. GitHub takes no pictures from outside its own pages, so the pictures stay on the board.
+
+**squad-kit's own code.** Its pull request goes to squad-kit's main repo (the `upstream` remote, else the repo its
+package names), into its default branch, and its owners merge it: squad-kit never does, a maintainer's own clone too. The review goes into the pull
+request's text, note by note, so they read it while reviewing. The story says **Waiting for the owner to merge**, out of
+your release, and squad-kit watches the pull request every few minutes:
+
+- **The owner left notes:** the story waits for you with each note (where, who, what), and two ways out. **Fix these**:
+  the Builder fixes them (20 at most at once; the rest come back on the next card), the checks, the review and your
+  Looks right run as usual, then squad-kit sends the fix to the same pull request and answers "Fixed in <commit>" on
+  each note whose lines the fix really changed. A question, or a note the fix did not touch, is left for you to answer,
+  with why. **Answer them yourself**: the story goes on waiting for the owner. Only notes from people who can change
+  that repo count; anyone else's, a bot's and your own are left out.
+- **Merged by the owner:** the story is done. Your copy and your main catch up by themselves when they only fell
+  behind.
+- **Closed without merging:** the story says so, with **Send it again** (a new pull request) and **Leave it closed**.
+  Opened again by the owner, it waits again. A clash with newer work there is said once, with what to do.
+
+On squad-kit's own code without gh, the story still shows "Send it as a pull request" (the push and GitHub's page), and
+says how to let squad-kit do it next time.
+
+Terminal: `squad pr <ticket>` shows where the pull request went, where it stands and the owner's notes; `--fix`,
+`--leave` and `--leave-closed` are the buttons. Send it again is `squad decide <ticket> 1`; **Check again** is `squad
+check-merge <ticket>`.
+
+### Contributing to squad-kit
+
+On squad-kit's own code, `squad contribute` shows the checklist before your first pull request, and squad-kit can do
+each step for you:
+
+1. **Signed in to GitHub**, or the steps.
+2. **Your own copy.** Cloned squad-kit itself and can't send changes there? **Make my copy** (`squad contribute
+   --fork`) makes your fork on GitHub, then `origin` points at it and `upstream` at squad-kit. Nothing in your history
+   changes.
+3. **Up to date with squad-kit**: how far behind. **Bring it up to date** (`squad contribute --sync`) uses GitHub's own
+   sync, then moves your main forward. When your copy or your main has changes of its own, it says so and forces
+   nothing.
+4. **The rules** the checks hold, from CONTRIBUTING.md.
+5. **A big idea?** **Tell the maintainers first** (`squad contribute --idea "<title>" --text "<idea>"`) gives GitHub's new
+   issue page, filled in. You read it and send it; squad-kit posts nothing in your name.
+
+REST (under `/p/<project>/api/v1`):
+
+| Call | What |
+| --- | --- |
+| `GET /tickets/<id>/pull-request` | `{ ticket, pr, to ("own", "owner" or "none"), into, base, state, line, notes, lookedAt, since, actions }`. `state`: open, merged, waiting, notes, fixing or closed. Each note: `{ id, kind, who, text, file, line, url, at, changes, state ("new", "fixing", "fixed", "left"), fixedIn, answered }`. Each action: `{ id, name, command }`. |
+| `POST /tickets/<id>/pull-request/fix` | Fix these. Answers with the same view. |
+| `POST /tickets/<id>/pull-request/leave` | Answer them yourself. |
+| `POST /tickets/<id>/pull-request/leave-closed` | Leave it closed. |
+| `GET /contribute` | `{ self, line, host, main, copy, items }`; each item `{ id, title, state ("done", "todo", "blocked", "info"), line, steps, points, file, action }`. |
+| `POST /contribute/fork` | Make my copy. `{ line, checklist }`. |
+| `POST /contribute/sync` | Bring it up to date. `{ line, checklist }`. |
+| `POST /contribute/idea` | `{ "title": "…", "text": "…" }` gives `{ link }`, the filled-in new issue page. |
+
 ## The window
 
 Agents don't get free commands for the app, the browser or the checks. squad-kit gives them a few fixed tools, "the
@@ -570,13 +642,14 @@ REST (under `/p/<project>/api/v1`):
 
 Upload a requirements document (a BRD) and the Analyst breaks it into epics, features and stories. You review it
 as a **tree** (the main view, with a side panel to edit each part) or a **map** (boxes and lines, for presenting),
-approve it, send it to Azure DevOps if you like, and press **Build continuously**. A breakdown waiting for your
-answers shows in **Waiting for you** and in the sidebar's count. The whole flow is in
+approve it, send it to your tracker (Azure DevOps or GitHub) if you like, and press **Build continuously**. A breakdown
+waiting for your answers shows in **Waiting for you** and in the sidebar's count. The whole flow is in
 [From a BRD to a built product](requirements.md).
 
 ## Other pages
 
-- **Backlog**: your tracker's sprint, in backlog order. **Start** puts an item on the board.
+- **Backlog**: your tracker's sprint, in backlog order (a GitHub Project's own order, or the newest issues first).
+  **Start** puts an item on the board.
 - **Waiting for you**: this project's cards, all of them.
 - **Releases**: the next release, ready to read and release, and every past release with its notes and the
   bugs found after it. A release whose push was refused says why in plain words. **It reached it another way** closes
@@ -619,6 +692,9 @@ builds.
   folder) that has everything is used as it is and never changed; one that lacks something is left as it is, and squad-kit
   gets its own. On Windows and Linux computers with an Arm chip, Google's emulator doesn't run yet: the line says so.
   **Android Studio** shows as Optional: squad-kit doesn't need it.
+- **GitHub's tool (gh)**, Recommended when the project's code is kept on GitHub: it opens and merges the pull
+  requests, signed in as you. Signed out shows as missing, with one line that says so. Without it, the work merges on
+  this computer, as before.
 - **You install it**: the line says why squad-kit can't ("needs your Apple ID"), gives short steps and the official
   page. Press **Check again** after installing. On Mac and Linux, Check again reads your terminal's PATH, so a tool you
   just installed is found without closing squad-kit, and the agents squad-kit starts after find it too.
@@ -981,6 +1057,37 @@ Terminal: `squad config set quality best`, `squad agent builder`, `squad agent b
 - **Desktop notices**: on or off, for this browser. **Turn on** says at once that the browser is asking; if the
   browser doesn't answer, it says how to allow notices for the page (and, on a Mac, in System Settings ›
   Notifications). When they are on, it sends one test notice.
+- **Tracker**: where stories come from. Pick **Azure DevOps** or **GitHub**, fill in what it asks, then **Save and
+  check**: squad-kit checks the settings with the tracker before it saves them, and the Status row says who is signed in.
+  - **Azure DevOps**: organization, project and a token, which stays on this computer.
+  - **GitHub**: squad-kit signs in with GitHub's own tool, `gh`, and keeps no token. When gh is missing or not signed in,
+    the steps show above the settings: install GitHub's tool (cli.github.com), `gh auth login`, and for a Project
+    `gh auth refresh -s project` (Issues alone never need that right). Pick the **Repository** (your project's own, from
+    its git remote, at first) and where the stories come from: **Issues**, with any **Labels** (all of them) and
+    **Assigned to** (a login, or `@me`), or **A Project**, picked from the owner's open Projects or typed as its number
+    or address (one under another owner too), with an optional **View** (its filter picks the stories) or **Only with
+    Status**. Under **More**: the Status for each of squad-kit's steps (Not started, In progress, Merged, Released),
+    the one that fits its name best unless you pick another, and **Stories from anyone**. It is off: only issues
+    written by the repo's owner, the organization's members and its collaborators reach the squad, so a stranger's
+    issue on a public repo never steers the agents.
+    Issues show as `#40`, or `owner/repo#40` for another repo's issue on the board, and become tickets named `GH-40`.
+    Labels are tags; the `bug` label or the Bug issue type makes a bug; a Project's iteration field gives the sprints
+    (the Backlog opens on the one running now, else the next, else the newest), and its Priority (first option highest)
+    and Points fields are read. Parents come from sub-issues, and what a story needs from "blocked by". On a board an
+    item only moves forward. The issue closes once the work is really in: the pull request says `Closes #40`, and a
+    pull request that waits for an approver, or for the owner of another repo, leaves it open until it is merged. A
+    merge on your computer leaves it to the release. Questions, answers, plans and pull request links
+    are comments on the issue, and a reported bug becomes an issue with the bug label. **Send to GitHub** on a breakdown
+    makes epics, features and stories as issues (the organization's issue types when it has them, else the labels
+    `epic`, `feature`, `story`), with sub-issues and "blocked by" links. GitHub has no wiki for squad-kit to read. The
+    Backlog reads at most 500 items at once and says so when there are more: a sprint, a view or a Status narrows it.
+  - **Set up before 1.3.21?** A project that had GitHub as its tracker before only reads it: pulling works, but no
+    move, comment, bug or breakdown goes to GitHub until you press **Save and check** once (or run the command below).
+    Settings says "Connect again to let squad-kit update GitHub." The updates wait meanwhile and go once you connect.
+  - Terminal: `squad config set tracker` asks for each setting;
+    `squad config set tracker --type github --field repo=owner/name from=project board=2` sets them at once
+    (also `labels=`, `assignee=`, `view=`, `status=`, `anyone=yes`, and `stage-in-progress=` and so on for the Status
+    of each step). `squad doctor` checks the same sign-in: gh found, signed in, and the Projects right for a Project.
 - **How you pay for Claude**: squad-kit finds out (subscription or API key); change it here if it is wrong. With an
   API key: a budget per ticket and per month. Terminal: `squad config set payment`, `squad config set budget`.
 - **Also read** and **Also write**, for engineers, where the guard runs: files or folders outside its copy that the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squad-kit",
-  "version": "1.3.19",
+  "version": "1.3.21",
   "author": "Momen Yasser <momenysr@gmail.com>",
   "description": "Your AI Engineering Squad transforms ideas into production-ready software.",
   "keywords": [