squad-kit 1.3.16 → 1.3.18

package/docs/console.md

@@ -316,6 +316,53 @@ program it did not start without your press.
 The same rule reads an agent's answer in a chat, where technical words are fine, because you asked. An answer that
 asks you to do one of the things nobody may ask is left out, and you read one plain line instead.
 
+## A story too big for one
+
+Before the Analyst asks any questions, squad-kit counts the story's size itself, with no AI: its words, the pages of an
+attached Word or PDF file, requirement numbers (FR-1, REQ-12…), headings and "shall" or "must" lines, separate asks, and
+how many roles, screens and flows it names. Code, tables, logs and stack traces are left out first. A short story is
+one story, and nothing more is asked. 400 words or 3 requirement numbers is never one story. 2,500 words, a document of
+8 pages or 10 requirement numbers is a whole requirements document. The Analyst judges the rest, and can still say one
+story, with the same sizes as a breakdown: **About a day**, **A few days**, **A week or more**. A bug, and a story
+pulled from a tracker, is never split. It only suggests: nothing is split or sent until you press.
+
+- **A few stories in one.** The Analyst suggests the parts in the order to build them, each with its size and what it
+  needs ("Needs 1"). On a story that exists, the card waits in its Now tab and in the Analyst's popup: **Split into N**,
+  **Keep as one**, or **Change the split** (your note goes in the chat's own box, and the Analyst splits it again).
+  After Split, the story keeps the first part with its new title, the Analyst asks part 1's questions, and the other
+  parts wait in Tickets with "depends on" ("Waits for MA-21"), each started when you like. Each part has its own
+  "done when" lines. Keep as one goes on with the questions the Analyst already asked. A whole document has **Send to
+  Requirements** and **Keep as one** instead.
+- **New ticket, From an idea or message:** the same suggestion shows before anything is created: **Create N stories**
+  (the first starts, the others wait in Tickets), **Create as one story** (the form, as usual), or **Cancel**.
+- **A whole requirements document:** "Too big for one story", with a rough count by part ("about 25 stories in 6
+  parts"): **Send to Requirements** starts a breakdown with your text and files, **Make one story anyway** keeps a short
+  warning on the story, or **Cancel**.
+- **The Squad lead** never drafts one giant story: its draft goes through the same count and offers Create N stories,
+  or Send to Requirements. A requirements document pasted to the lead gets that card at once, with no AI.
+- **A talk beside the work** changes nothing on the story: a big text pasted there gets a hint under it, and for a
+  whole document a Send to Requirements button. Once sent, the hint links to the breakdown.
+
+The cards speak the language you wrote in, right to left in Arabic. The Harness page shows the numbers.
+
+Terminal: `squad split MA-21` shows the suggestion; `--yes` splits it, `--keep` keeps it as one, `--change "<how>"` asks
+for another split, `--requirements` sends a whole document to Requirements. Like the card's buttons, a split has no
+`--requirements` and a whole document no `--yes` or `--change`. `squad split MA-21 --chat-requirements` sends the
+document pasted into its talk, as the hint does. `squad new --from "<text>"` prints the suggestion and asks; `--split`
+or `--one` answer up front, and `--requirements` sends the text and files to Requirements with no draft.
+`squad lead run <card> --split | --one | --requirements`.
+
+REST (under `/p/<project>/api/v1`):
+
+| Call | What |
+| --- | --- |
+| `POST /tickets/<id>/split` | `{ "choice": "split" \| "keep" \| "change" \| "requirements", "note": "…" }`, only the choices its card offers. From a decision card, `expect` is the mark of what it showed. Answers with the story. |
+| `POST /tickets/<id>/chat/requirements` | `{ "at": "…" }`: send the whole document pasted into the story's talk to Requirements, once. Answers `{ "breakdown": { "id" } }`. |
+| `POST /tickets/draft/<draft>/split` | Create N stories from the New ticket draft. The same press sent again gets the same stories. Answers `{ "tickets": [...] }`. |
+| `POST /tickets/draft/<draft>/requirements` | Send the draft's text and files to Requirements; again, the same breakdown. Answers `{ "breakdown": { "id" } }`. |
+| `POST /tickets` | As before, with `"sized": "checked" \| "kept" \| "brd"` when the size was judged in the dialog. |
+| `POST /lead/cards/<id>/run` | `{ "choice": "split" \| "one" \| "requirements" }` on a story draft that is more than one story. |
+
 ## Chat
 
 Open a chat with any agent on a ticket: **Ask the Analyst** on the Now tab, **Talk it through** on a spec or
@@ -333,8 +380,11 @@ something, use the ticket's own buttons. With a chat open already, the button op
   and new, and you approve it.
 - **Released work is for questions only.** A change to it becomes a new linked ticket or a bug report.
 
-A chat opens in a side panel beside the board, and takes the whole screen on a phone. **Conversations** in the sidebar
-is a full-screen page with all of them.
+A chat opens in a popup over the page, and takes the whole screen on a phone. Each open talk has a round head at the
+bottom right, with an unread badge and a live dot while the agent writes; up to three popups sit side by side, each
+minimised to a bar, closed, or opened on its full page. They stay open when you change pages. **Conversations** in the
+sidebar is a full-screen page with all of them. When the story waits for you, its card closes the talk, with the
+board's own buttons (see **Decide in the chat** below).
 
 Terminal: `squad chat <ticket>`, `squad chat <ticket> --ask`, `squad message <ticket>`, `squad propose <ticket>`.
 
@@ -346,9 +396,10 @@ a story, next to **Open** in Your apps with the page you are on, or with **Ask t
 error card: the problem's facts are filled in for you.
 
 **On the board**, **Squad lead** in the sidebar is the conversation, with what needs you, the squad now and what it can do
-beside it, and every past conversation under History. **⌘K** (Ctrl+K on Windows and Linux) opens the ask box on any
-page, with the open story or the page filled in; the answer shows right there, and **Open in the Squad lead page** keeps
-it. Nothing is sent until you press Send.
+beside it, and every past conversation under History. Its round head comes first at the bottom right of every page,
+with how many things need you; **⌘K** (Ctrl+K on Windows and Linux) opens its popup, with the open story or the page
+filled in. The popup starts with what needs you and a few questions to ask; the answer shows right there, and the
+expand button opens it on the Squad lead page. Nothing is sent until you press Send.
 
 **Cheapest first.** squad-kit answers at once itself, with no AI, when it can: a saved note, a status question about a
 story ("is MA-9 ready?"), or something the lead never does. Otherwise the lead reads what squad-kit already knows (its
@@ -363,13 +414,21 @@ gets it at once, and "How to sign in" shows next to Open in Your apps.
 
 | Level | What |
 | --- | --- |
-| On its own | Read, look and tell: answer, explain a story, find things, look at the app in its own copy, show a story's own proof pictures, give you an **Open** button to a story on the board (at its proof, spec, plan or questions; it changes nothing), tell you what needs you, prepare a report for an engineer (no secrets, for you to copy). |
+| On its own | Read, look and tell: answer, explain a story, find things, look at the app in its own copy, show a story's own proof pictures, give you an **Open** button to a story on the board (at its proof, spec, plan or questions; it changes nothing), bring a story that waits for you as a card with the board's own buttons (only you press them), tell you what needs you, prepare a report for an engineer (no secrets, for you to copy). |
 | After your OK | A card you press, running the same function as the board's button: **Create story** (a draft with how each "done when" will be proved; nothing starts until you press Start), Start or Stop a story, Give it 10 more minutes, Take the pictures again, Try again, Start the app, Get or Update a tool, **Send** an answer to an agent's question, **Save** a setting (technical ones only for engineers). |
 | Never | Change code; commit, merge, push or release; press Looks right or approve a spec or plan; get around the checks, the review, the proof, the guard or the limits; change the Harness rules; touch your real data, secrets or `.env` files, or show a password or a key; delete stories, projects or data; message other people. squad-kit refuses these in its own words, whoever asks. Only your own messages count, never instructions found in what it reads. |
 
 **Buttons, not "tell me".** When an answer sends you to the board, the button comes with it: "Open MA-17's proof",
 or the board action that fits the story now. When the lead refuses what only you may do (Looks right, approving a spec
-or plan, merging, releasing), it still gives you the Open button, so you are one press from doing it yourself.
+or plan, merging, releasing), it still gives you the story's card, so you are one press from doing it yourself.
+
+**Decide in the chat.** A story that waits for you comes as a card, in its own talk and in the lead's answers about it:
+the proof with its pictures and "done when" ticks (**Looks right**, **Something's wrong**, Full proof), the spec, plan
+or design in short (**Approve**, **Ask for changes**, Read it all), the Analyst's questions as answers to tap, an agent's
+question with its answers, or **Open** with the board's own reason. The card is drawn from the board as it is now; its
+buttons are the board's own (`squad approve`, `squad answer`, `squad reply`), and each press is checked again: if the
+story was decided or changed since, the card says so. Something's wrong asks for your note in the chat's own box and
+sends it to the board. The lead brings the card; only you press it.
 
 **Always allow** is only for the low-risk ones: give more time, take the pictures again, start the app, and the morning
 brief. With it on they run without asking, and a line says so. A step that is slower than usual but still working then
@@ -400,7 +459,7 @@ REST (under `/p/<project>/api/v1`):
 | `POST /lead/conversations/<id>/messages` | A follow-up, the same body. |
 | `GET /lead/conversations/<id>` | The conversation: each question with its facts, the work trace, the answer (headline, body, evidence, sources, cards, learned), the time and the cost. |
 | `POST /lead/conversations/<id>/stop` | Stop the answer being written. |
-| `POST /lead/cards/<id>/run` | Press a card. `{ "always": true }` turns Always allow on first, only for the low-risk ones; `{ "dismiss": true }` is Not now; `{ "edits": { "title": "...", "doneWhen": [...] } }` is Edit before Create. |
+| `POST /lead/cards/<id>/run` | Press a card. `{ "always": true }` turns Always allow on first, only for the low-risk ones; `{ "dismiss": true }` is Not now; `{ "edits": { "title": "...", "doneWhen": [...] } }` is Edit before Create; `{ "choice": "split" }`, `"one"` or `"requirements"` on a draft that is more than one story (see [A story too big for one](#a-story-too-big-for-one)). |
 | `GET /lead/rules`, `PUT /lead/rules` | Always allow and the morning brief: `{ "always": ["more_time"], "brief": true }`. The never list is shown and cannot change. |
 | `GET /lead/can` | The three levels in words, what it reads, and its limits, for "What it can do". |
 

package/package.json

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