squad-kit 1.3.18 → 1.3.19

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-BV9HD-7y.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CT6ZEPGo.css">
+    <script type="module" crossorigin src="/assets/index-Cn6JuFKc.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DVTP7K3b.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/console.md

@@ -265,6 +265,98 @@ When the proof is ready, or a check stopped the ticket, the row of steps says **
 command and what it printed, for engineers. It is on Try it yourself, Your apps, the setup after a merge, and the
 tests on the Overview.
 
+### The right proof for each "done when"
+
+Not every story needs pictures. In the spec, each "done when" has a chip that says how it will be proved, with one
+plain line on why under it:
+
+| Kind | The proof | Made by |
+| --- | --- | --- |
+| **Screen** | Pictures before and after, as above. | The Tester, through squad-kit's browser |
+| **Data** | The rows of the story's own database before and after the action, read only. Changed cells are marked, new rows too. | The Tester, with `read_rows` |
+| **API call** | The call and its answer. | The Tester, with `ask_api` |
+| **Test** | The one test the story added or changed that proves it, its steps in plain words, and "It failed before the change and passes now". | squad-kit runs that test on main's code (with the story's test file put there) and on the story's code |
+| **Not on a screen** | The reason you approved, and what the Reviewer checked in the code, the data and the logs. | The Reviewer, in its review |
+
+- **The Analyst proposes** the kind for each line. **squad-kit's own rules** then lock a line to Screen when it is about
+  what someone sees, and when the story changes screen files and no other line has a picture. The lock shows on the
+  chip, with the rule under it. No agent can move a locked line away from Screen.
+- **You change a kind** with the chip's menu before you approve the spec. On a locked line the other kinds are off.
+  Not on a screen asks for a reason first. After the approval the chips are read only: **Ask for changes** changes a
+  kind, and a change can never unlock a line.
+- **A test that also passes on main is no proof.** The line shows **Not shown yet** and goes back to the Builder, to
+  write a test that fails without the change. A test that fails on the story's code is **Not working yet**. "It failed
+  before the change" counts only when the test tool ran that very test on main's code, matched by its whole name, and
+  its own check said no: a run stopped by an import, the setup, a missing tool or the time limit tells nothing, and
+  waits for you, with Try again and Continue anyway, like a test squad-kit cannot run there at all. squad-kit runs only
+  that one test, by its whole name (each case of a test written for `each`) and, where the test tool can, by its file
+  and line.
+- **A line that keeps something that already works** ("Paid bookings stay as they are") is **Test · stays as it is**.
+  The Analyst proposes it with the kind, and you turn it on or off in the chip's menu before you approve the spec. Its
+  test must pass on main's code and pass now: "Stays as it is: passes before and after". A test that fails on main
+  shows what it keeps did not work before, and waits for you. No agent sets it after the approval.
+- **The Tester names the test** from the list of test files the story added or changed, with their tests, that
+  squad-kit gives it. A test from before the story is never the proof.
+- **A planned picture is never dropped quietly.** When the Tester cannot make a Screen, API or Data proof, or no app
+  can start for it, it is Not shown yet, and after the retakes a problem on the card, never a silent Not on a screen.
+- **A story with no Screen line** starts no browser, never builds for the phone, and takes no pictures. When an API or
+  Data line needs the app, it starts headless.
+- **A project with no app to start** (a command-line tool, a library) has nothing to show, call or read: there is no
+  lock, the Analyst proposes Test or Not on a screen, and only those can be picked.
+- The Proof tab and the proof page show one block per line with its kind. A chat card shows each line's kind with a
+  short form of its proof. An old spec with no kinds is proved exactly as before.
+
+Terminal: `squad prove MA-21` lists the lines and their kinds. `squad prove MA-21 2 data` changes line 2;
+`squad prove MA-21 5 none --why "Nothing to show: the Reviewer checks the code"`. Not on a screen needs `--why`.
+`squad prove MA-21 3 test --keeps` makes line 3 stay as it is; `--no-keeps` turns that off.
+
+REST (under `/p/<project>/api/v1`):
+
+| Call | What |
+| --- | --- |
+| `POST /tickets/<id>/prove` | `{ "line": 2, "kind": "screen" \| "data" \| "api" \| "test" \| "none", "why": "…", "keeps": true }`, only before the spec is approved. `why` is needed for `none`. `keeps` (true or false, only with `test`) turns "stays as it is" on or off; left out, a Test line keeps what it had. A locked line takes only `screen`. Answers with the story. |
+
+## The review, in the pull request
+
+The Reviewer writes each note with the file it is about and the line in that file. squad-kit keeps every round on the
+story (its `review.md`): the round's number and time, approved or changes asked, and each note, numbered across the
+story. Each note stands one of three ways:
+
+| State | What it means |
+| --- | --- |
+| **Fixed in `a3f9c21`** | squad-kit saved the work as the Reviewer read it, then the Builder's fix, and git shows the fix changed the note's own lines (or, with no change on them, the nearest note within 2 lines; a removed file fixes nothing). The Reviewer's next round sees it and can reopen it. A note about a whole file, a note git cannot place, or a note of an approved round that a change you asked for touched, is fixed only when the Reviewer's next round says so, and a note about a whole file only if its file really changed. |
+| **Went past** | You went on without it, with your reason on the record: **Go past…** on the note, or **Continue anyway** on a review that stopped. Only you can. |
+| **Open** | Nothing settled it yet, for example a small note the Reviewer approved with. |
+
+The **Changes** tab starts with the review: each round, each note on its file and line with where it stands, the
+Builder's fix commits, and who pressed Looks right. Stories from before this keep their notes as round 1, with no file
+or line.
+
+At Looks right, the pull request is the full record. Its description has what was asked, each "done when" with how it
+is proved and a link to its proof, the review (rounds, notes fixed and gone past, the Builder's changes after review),
+the notes you went past with your reason, and "<you> approved: Looks right, <date and time>". Each note is a thread on
+its file and line: Fixed with its commit, Went past with your reason (closed), or Open (active). One more closed thread
+says who pressed Looks right: squad-kit signs in with the project's token, so it never votes or approves in your name.
+squad-kit writes the threads only once the pull request is merged, so a thread can never hold the merge up: right after
+its own merge, or when it sees that someone merged it on the code host. If the code host says no, the story says so
+plainly, and **Write it again** on the Changes tab tries once more, only on a merged pull request: it adds the threads
+that are missing and leaves the others as people left them. Every word the Reviewer, the Analyst or you wrote goes into
+the pull request as plain text, one paragraph each: no link, picture, heading or mention of theirs shows there.
+
+A project with no pull requests gets the same record in short in the merge commit's message, under its title: the
+rounds, one line per note with where it stands, and who pressed Looks right.
+
+Terminal: `squad review MA-21` prints the review the way the Changes tab shows it. `squad review MA-21 --past 3
+--reason "<why>"` goes past note 3; `squad review MA-21 --write` writes it into the pull request again.
+
+REST (under `/p/<project>/api/v1`):
+
+| Call | What |
+| --- | --- |
+| `GET /tickets/<id>/review` | Every round with its notes, each note's state, the counts, the fix commits, who pressed Looks right, and whether it is in the pull request (`posted`). |
+| `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" }`. |
+
 ## 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
@@ -277,6 +369,8 @@ back the result. Each run has its own key, which stops working when the run ends
 | `look_at_page` | Opens a page, does the steps, and gives back the address and what is on the page. It saves no pictures. | Tester, Builder, Reviewer |
 | `start_app`, `stop_app`, `app_status` | Starts this story's copy with the project's own start command, on a free port when the usual one is taken. Stops only what squad-kit started. Says whether it runs, with its last lines. | Tester, Builder |
 | `run_checks` | Runs the project's saved test, lint or build command, inside the guard, where a browser can start. With `only`, it runs one test file on its own with the project's own test tool, for a quick fix. A failure is not run again. | Tester, Builder |
+| `ask_api` | Asks a part of the running product (only its own address), and saves what was asked and answered. | Tester |
+| `read_rows` | Reads at most 20 rows of one table of the story's own database, read only, before and after the Tester's action, and keeps both in a new file of each round for a Data proof. squad-kit builds the one query itself from a table and the columns each row equals; it takes no query, never writes, sends no backslash or control character, stops a read after 20 seconds, and hides secret columns and fields (a password, a token, a key: by whole word parts, so `passport` shows) and anything shaped like an address. A secret that changed says so with no value. A story with no database of its own has nothing to read. | Tester, on a story with a Data line |
 | `i_am_stuck` | Tries squad-kit's own fixes (see below). | Every agent on a ticket |
 | `read_board`, `read_story`, `read_decision`, `read_records`, `read_logs`, `read_guide` | Reads squad-kit's own records: the board, a story, the decisions, requirements, releases, usage, the Tools page, the Harness rules, its notes, its log (secrets taken out) and its guide. What comes back is marked as data. | Squad lead |
 
@@ -434,10 +528,19 @@ sends it to the board. The lead brings the card; only you press it.
 brief. With it on they run without asking, and a line says so. A step that is slower than usual but still working then
 gets 10 more minutes by itself; one that looks stuck still asks you.
 
-**It comes to you.** "Needs you" lists what waits for you, each with the lead's check-in in plain words ("MA-7 is ready
-for your check: 5 pictures, checks pass, Reviewer approved") and its ways out as cards. "The squad now" shows who works
-on what. Turn on the **morning brief** for a short summary since yesterday evening: what merged, who is on what, what
-stopped, and what the AI used. None of these call the AI.
+**It comes to you.** "Needs you" lists what needs a press from you, each with the lead's check-in in plain words
+("MA-7 is ready for your check: 5 pictures, checks pass, Reviewer approved"; a story proved without pictures says how,
+"proved by a test") and its ways out as cards, each button named by what it does ("Take the pictures again", "Always
+take them again"). Its number is the top bar's, everywhere. News, such as a released story with a decision that came
+after its plan, goes to "What's new" and is never counted. Who works now is one line under the lead's name. "Hello"
+or "Thanks" is answered at once from the board's own numbers, in your language, with no AI. Turn on the **morning
+brief** for a short summary since yesterday evening: what merged, who is on what, what stopped, and what the AI used.
+None of these call the AI.
+
+**One talk in one place.** While a page shows a talk itself (the Squad lead page, the Conversations page with that talk
+picked, a story's Conversation tab), its popup hides and its head shows an "on this page" ring; pressing it brings the
+page's own box into view. Every chat opens at its newest message, or at the first unread one under a "New" line;
+scrolled up, a chip counts the new messages and takes you down.
 
 **Limits.** Balanced level by default. One question may use what the Quality setting allows it (on Best, $3 or 60
 turns) and 8 minutes; the lead's answers may use $10 a day at API prices, then it answers again the next day. Each
@@ -453,8 +556,8 @@ REST (under `/p/<project>/api/v1`):
 
 | Call | What |
 | --- | --- |
-| `GET /lead` | The conversations, Needs you, The squad now, the morning brief when it is on, your rules, and today's cost and limit. |
-| `GET /lead/needs-you`, `GET /lead/squad-now`, `GET /lead/brief` | Each on its own, for the rail and the phone. |
+| `GET /lead` | The conversations, Needs you, What's new, The squad now, the morning brief when it is on, your rules, and today's cost and limit. |
+| `GET /lead/needs-you`, `GET /lead/squad-now`, `GET /lead/brief` | Each on its own, for the phone. |
 | `POST /lead/conversations` | Ask: `{ "text": "...", "context": { "from": "app", "path": "/my-bookings" } }`. The context is `board` (with `page`), `app` (with `path`), `story` (with `story`) or `problem` (with `problem`: slow, stuck, waiting or error, and `story` or `error`). `"fresh": true` looks again past a note. It answers with the conversation: answered when squad-kit answered itself, else `thinking` until the answer is in. |
 | `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. |

package/package.json

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