squad-kit 1.1.1 → 1.2.1

package/CHANGELOG.md

@@ -7,6 +7,261 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.1] — 2026-11-05
+
+A patch about not losing work and never reaching a dead end. It also moves the project's commit hooks into the guard.
+Nothing changes in how you work with the squad.
+
+### What you type stays
+
+- **Text you type survives** a reload, a closed tab or a dialog closed by mistake: answers, comments, new tickets, bugs
+  and the BRD box are kept for each project, ticket and field, and cleared once sent.
+- **Skip** asks first. Dialogs with files in them ask before closing. Enter works in an **Other** answer.
+
+### When something goes wrong
+
+- **The app going down shows at once.** Within 5 seconds a banner sits over every page, nothing pulses as if it were
+  still working, and the banner goes by itself when the app is back. An update that does not come back gets it after 2
+  minutes.
+- **One error no longer takes the app down.** Each squad turn is guarded, and an error in the screens shows a page with
+  a way back. A full disk or a moved folder holds that project with one banner, and it carries on by itself.
+- **A network blip waits and tries again**, 4 times over about 15 minutes, and never lowers the model level. A merge cut
+  off by a blip is tried again too.
+- **A moved folder is found.** The story copies' links are repaired when the squad starts, at **Looks right** and when a
+  step opens a copy. Home follows a folder moved while the app runs.
+- **A refused release has a way out.** A teammate's push is merged and sent, never forced. A real clash gets the clash
+  card, and a protected main gets plain words and an engineer's steps.
+- **It reached it another way**: a new button on the Releases page, for a release merged by hand. It needs a reason and
+  looks on the remote first. If the release is not there, it warns and asks a second time. Terminal:
+  `squad release --mark-sent --reason "…" [--anyway]`. `squad release` also takes the version with or without the `v`.
+- **Take it**: a new button on a ticket whose owner cannot work on it. Terminal: `squad take-back <ticket> --reason "…"`.
+- **A ticket is never overwritten** by another with the same id, and new ids skip the ones already pushed.
+- **The home folder is refused** by `squad init`, setup and the first commit, and a leftover `~/.squad` is ignored.
+- **The link lasts across tabs.** With no key in the link, the page says to run `squad`.
+- **Stop and closing the board** end a running hook, and closing takes seconds. `squad | tee` stops cleanly, and a run
+  whose output goes to files keeps running when its terminal closes.
+- **An agent's tool calls** no longer fail with a dropped connection after 5 quiet seconds.
+
+### The project's commit hooks
+
+- **They run once, when a change is saved, in the guard, on a stand-in branch.** A hook cannot move a real branch, plant
+  a hook or change a git setting. The real commit is made after, outside the guard, with your signature if your git
+  signs. A crash or a failed signature no longer moves a branch or leaves an unsigned commit.
+- **Every refusal gets a card**: **Let the Builder fix it**, **Fix it yourself**, **Try the save again**, or **Save
+  without this check**. Saving without it needs a reason, which stays on the ticket, the pull request and the release
+  notes. Builds by itself never skips a hook.
+- **Refused code cannot slip through.** Work saved past a refusal is checked whole at **Looks right**, and the branch
+  goes back as it was if the hook still says no.
+- **The Builder cannot change the check to pass it.** Hook files, their settings and their `package.json` keys go back,
+  with one plain line. What a hook calls, like lint rules and tests, stays the Builder's, and the Reviewer reads it.
+- **husky 9 now runs in a story's copy.** Before, its hooks silently never ran there.
+- **squad-kit runs no other hook**: no `pre-push`, `post-merge` or `post-checkout`, since the project's own checks have
+  run by then. Your own terminal still runs them. Git LFS files still upload when squad-kit pushes.
+- **A hook folder with a common name** (`hooks`) no longer costs you work in `src/hooks`. `npx` works in a hook with no
+  packages installed.
+
+### Security
+
+- **`.git` and git's own folder are read only** for the project's commands and for agents.
+- **squad-kit's own git starts nothing a repo names by itself**: no file monitor, no diff program, and nothing from a
+  nested repo, which also stays out of commits.
+- **The app answers only at its own address.** Host and Origin are checked on every route, a key in the link works for
+  reads only, and HTML and SVG from a project download instead of opening at the board's address.
+
+### Known limits
+
+- **A hook built to do harm could change a file in git's store of objects.** A project with no commit hooks is not
+  affected. The next patch closes this by running hooks in a throwaway git folder. See [SECURITY.md](SECURITY.md).
+- A hook that reads the branch name sees the stand-in, `squad/saving/<branch>/now`. A strict one says no, and you get
+  the card.
+- Setup in your own checkout no longer installs husky's hooks. On a fresh clone they stay off until you install them.
+- Stop in the middle of lint-staged leaves its backup in `git stash list`. Your work is safe.
+
+## [1.2.0] — 2026-11-05
+
+squad-kit 1.2 is about trust: squad-kit shows that it understands your project, says what the work really cost, and
+makes the squad's work harder to fake. It also takes a whole requirements document and builds it, story by story.
+Windows is less protected and not fully tested yet (see What's safer).
+
+### What's new
+
+#### From a BRD to a built product
+
+- **A new Requirements page** (after Overview). **Add a BRD**: a PDF, Word or Markdown file, or pasted text, with
+  mockups if you have them. The Analyst reads it live and asks only about what is **missing in the BRD** or where
+  **two parts clash**. Then it writes epics, features and stories, each with its checks (Given, When, Then), size,
+  needs and its place in the document.
+- **Review it as a tree or a map.** Rename, rewrite, move, add or remove any part, or ask the Analyst to redo one.
+  An estimate from this project's own tickets: "20 stories, about $140 and 6 hours, 2 at a time". Nothing is built
+  or sent before **Approve breakdown**.
+- **Send to Azure DevOps**: epics, features and stories with parent and dependency links, into the backlog. **Send
+  changes** updates only what changed. squad-kit never deletes there, and a cut-off send makes no doubles.
+- **Build continuously**: each story becomes a ticket on the new **Builds by itself** track, in the order its needs
+  allow, within the parallel limit and the budgets. No questions, the plan is approved by itself, small choices are
+  listed under **Decided for you** (press **Change** on any), and it merges by itself once the checks, the review
+  and the screenshots pass. It stops only for a gap, a clash or a failed check, and then only that story and the
+  ones that need it wait. Releases stay your button.
+- Terminal: `squad requirements add|show|answer|edit|move|approve|send|build|start|…`, `squad decided`. See
+  [From a BRD to a built product](docs/requirements.md).
+
+#### Proof you can read
+
+- **squad-kit takes the screenshots itself, with its own browser.** The Tester says which pages, steps and sizes.
+  squad-kit opens the story's own copy of the app, does the steps and takes the pictures.
+- **One or more pictures for each "done when"**: one per part or case, up to 6.
+- **Each "done when" gets a verdict**, from the Tester and squad-kit's own check of all its pictures together:
+  **Met**, **Not working yet** (a picture shows it does not work), **Not shown yet** (the pictures do not show it
+  clearly) or **Not on a screen** (it cannot be shown at all, like an email or what happens after a restart). Not
+  working yet goes back to the Builder once, then it is a plain stop. Not shown yet goes back to the Tester up to 2
+  more times, keeps the good pictures and never reaches the Builder. Not on a screen keeps its reason and does not
+  stop the story, unless every "done when" ends that way.
+- **Also changed, not in the plan**: what the change touches beyond its plan, in the Reviewer's words. It never
+  blocks. You see it at your check, on a stop, on the ticket and in the release notes.
+
+#### Your turn
+
+- **Where to look**: each page the proof names, with the "done when" it shows.
+- **Try it yourself**: runs the story's own copy of the app, with the change in it and nothing merged, so you can
+  click through it before **Looks right**. It stops by itself when the story moves on. Terminal: `squad try <ticket>`.
+- **Ask a question** on every story, in every state: working, in the queue, waiting for another story, stopped, at
+  review, taken over or released. Whoever knows the story best answers: the Analyst before the build, the Builder
+  during and after it, the Tester once there are screenshots. It answers questions only, and the story stays exactly
+  where it is. Terminal: `squad chat <ticket> --ask`.
+
+#### First run and Overview
+
+- **Add project says what it found** (code with or without git, an empty folder, several repos, an older
+  squad-kit) and what happens next, before you confirm.
+- **A setup page with live steps**: project memory, the AI tool, the Architect reading the code, how to test and run
+  it, trying the tests, opening the app once with a screenshot, and your overview. Each step has its time; a failure
+  has a way out and never stops the setup. **Notify me when it is ready**. Quality is asked once here.
+- **The Overview page**, first in the sidebar: what the project is, who uses it, what it can do today, how its parts
+  fit together, things worth knowing, the rules found, the proof, and three ideas for a first ticket. It stays up to
+  date after every merged ticket.
+- **The rules the Architect found are proposals until you approve them** with **Looks right, start working**. They
+  used to be saved as approved without being shown. **Something is wrong** opens a talk with the Architect.
+- **An empty project asks "What do you want to build?"**, in your own words, in English or Arabic. The Architect
+  writes down what you want with first stories for it, and picks the technology itself when your first story is
+  planned. Terminal: `squad overview --build "what you want"`.
+- **squad-kit finds the commands of a project that started empty.** After the first build it reads how to test and
+  run the project from its files, and saves that. Nobody is asked.
+- Terminal: `squad setup`, `squad overview`, `squad demo --first-run`.
+
+#### Conversation and Cost
+
+- **Conversation opens on "What happened"**: one card per step with its time, a one-line summary and what it handed
+  in, drawn as the real thing. **Full log** keeps the detail, in plain words, with **Open it in Claude Code**.
+- **Cost follows how you pay.** On a subscription: "Included in your Claude plan. No extra charge.", the size of the
+  work and where it went, with the API-price figure shown as a value, not a bill. With an API key: real dollars, a
+  budget per ticket and per month, a warning at 80% and a pause at 100%.
+- **Averages per Quality setting** (cost and squad time per accepted ticket) on the Squad and AI page.
+- Terminal: `squad cost`, `squad config set payment`, `squad config set budget`.
+
+#### Tickets that depend on each other
+
+- **The Analyst and the Architect see the other open tickets** and the files they change.
+- **A design can depend on another ticket.** The ticket then waits before building: **Build on its branch**, **Build
+  anyway**, or **Wait** (it starts by itself when the other one merges). Terminal: `squad depends`, `squad build`.
+- **Bring in latest main** is a button on a ticket being built (`squad bring-in`).
+
+#### Releases
+
+- **Take a ticket out of the next release** before you release it (`squad release --without`).
+- **Released tickets' branches are cleaned up** on this computer, and on the remote when you ask (`squad branches`).
+  A branch with unmerged work is never deleted.
+- **A release cut off by a restart finishes or rolls back** cleanly on the next start.
+
+#### Also
+
+- **The ticket can go full width** (the button next to Close; remembered in this browser). **Hand over** and
+  **Propose a change** moved to the ⋯ menu, and Propose a change is also on the ticket's bottom bar, so the header is
+  one row at any width.
+- **The Waiting for you banner is one slim, calm row**, and stays readable beside a docked chat.
+- **The update banner shows what is new in every release since your version**, and **Check for updates** reads the
+  notes again.
+- **Free the port and try again** on a stuck Tester step, for programs squad-kit itself started.
+
+### What's safer
+
+- **Agents get fixed tools, "the window"**: `take_screenshots`, `look_at_page`, `start_app`, `stop_app`, `app_status`,
+  `run_checks` and `i_am_stuck`. An agent fills in the fields, squad-kit checks them, does the job itself and hands
+  back the result. There is no free command: only this story's app on this computer, only the project's saved
+  commands, only what squad-kit started. A request outside that is refused and written in the activity, and three
+  refusals in one step stop the agent.
+- **`i_am_stuck`**: when something technical is in an agent's way, squad-kit tries its own fixes (its browser, a free
+  port, starting the app again) and writes one plain line. It is never a question to you.
+- **Technical questions never reach you.** squad-kit reads each question an agent asks, with its choices and
+  everything shown with it, and does not trust the agent's label. A question about ports, commands, files or settings
+  goes back to the agent to decide. An agent that keeps asking stops in plain words. When another program holds a
+  port and going around it did not work, you get one plain card with no port in it: **Stop it** (with a confirm) or
+  **Skip the browser tests**.
+- **Some asks are refused and logged.** Asking you to change squad-kit's settings or protected files, to hand over a
+  password or a key, or to change git history never reaches you. One plain line goes in the activity. A reply in a
+  chat that asks for any of these is left out too.
+- **A second guard for the project's own commands.** The tests, lint, build, setup, the app's start and the release
+  pipeline run in squad-kit's own guard on Mac and Linux. They work normally, browser tests too, and can reach the
+  network, but they can't read your keys, sign-ins, browser profiles, squad-kit's own folder or the `.env` files in
+  your project folder. If a project truly needs a file outside its copy, one plain sentence says so, and an engineer
+  can allow it in Settings or with `squad config set allow-read <path>` and `squad config set allow-write <path>`.
+  `squad doctor` shows whether the guard runs here.
+- **Windows is less protected and not fully tested yet.** There, the agents' own commands and the project's own
+  commands have no guard, so they can reach other files on the computer. Use it on projects you trust. Settings and
+  the Squad and AI page say "Windows: less protected".
+- **"Not checked" instead of a green pass** when a project has no tests. You are asked once per project, with the
+  Architect's suggested test command. A project without tests also checks that the app starts.
+- **Weakened tests stop the ticket**: deleted tests, fewer tests, a changed test setup, or new skip/only markers, in
+  the common languages. **Continue anyway** needs a reason that stays on the record.
+- **Proof is verified**: each screenshot must be a real image taken in this step, and "after" must differ from
+  "before", unless the "done when" says the screen stays as it was.
+- **The Reviewer sees the whole change and the check results** in every round, not only the fix. In its review it can
+  also look at a page of the app itself (`look_at_page`).
+- **A change to the test command is tried first.** squad-kit runs the new command and the current one in the ticket's
+  copy, and keeps the new one only when it passes and runs at least as many tests. You choose only when it cannot
+  tell. Terminal: `squad test-command <ticket> --use | --keep`.
+- **The Builder's and Tester's commands run in Claude Code's sandbox** where the computer allows it: they write only
+  in the ticket's copy, its proof folder and a private package cache, can't read your keys, sign-ins or `.env`
+  files, and reach only package registries and the websites you allow (Settings, `squad config set hosts`). A
+  blocked command says what and why. `squad doctor` shows whether the sandbox runs here.
+- **Turn and spend caps per step** from the Quality setting. Reaching one keeps the work and offers **Give it more**
+  or **Stop**.
+- **Every command squad-kit suggests you copy quotes your text safely**, on the board and in the terminal.
+- **zod 4, the AI SDK 5 and diff 8** for the 0.x planner commands. This closes the last high alert. The planner's
+  file-read tool on the Claude Agent SDK path now works with ranged reads.
+
+### What's fixed
+
+- **Plain stop messages.** A stop says what happened in squad-kit's own plain words, with **Try again**. A tool's raw
+  error never reaches you: the exact words are in the ticket's Developer tab and the app log.
+- **A failed check runs once more** before anyone is sent to fix it, so a flaky test costs no Builder run. If it passes
+  then, the activity and the Developer tab say "failed once, passed when run again". Not after a Stop, a command
+  squad-kit had to end, or a file the guard blocked.
+- **The Builder is told about old failures**: the checks that already failed on the first run, before any story
+  touched the code. It fixes what its story broke and leaves other screens alone. The checks must still pass.
+- **A clash no longer stops a story too soon on Builds by itself.** While main keeps moving, squad-kit brings it in
+  again by itself, up to 3 times, with the checks, the review and the proof each time. If main has not moved, or after
+  the third time, you get the clash card. Other tracks show the card at the first clash, as before.
+- **Apps move to a free port by themselves** when another program holds the usual one: Your apps, the story's own copy
+  and Try it yourself. In Your apps this works when the start command or the app's code takes a port setting; if not,
+  one plain sentence says what is in the way. `--next-port` on `squad app start` and `squad app restart` is still
+  accepted, and now does nothing.
+- **squad-kit installs its own screenshot browser.** No `npx playwright`, and nothing to install by hand. The first
+  time, one line says "Setting up squad-kit's screenshot browser. This happens only once."
+- **The step timer counts only running time.** It stands still while a ticket waits for you, for another story or for
+  a free place, so "Taking longer than usual" no longer shows on a step that was only waiting.
+- **A restart is not a failure.** Restarting the board, Stop or the computer sleeping no longer counts as a failed
+  try or raises the model's effort. The Builder carries on with the same step in the same conversation, instead of
+  starting the work again, and the step's clock keeps its time ("resumed after a restart").
+- **Nothing is left behind.** When a step ends, on Stop, and when the board restarts or quits, squad-kit stops every
+  program it started for the ticket, including test servers that left their process group. It finds them by where
+  they run: inside squad-kit's own copy of the code, never your folders or Your apps.
+- **squad-kit clears its own leftovers before the checks** and says so in one activity line. If an agent asks about a
+  busy port that squad-kit caused, squad-kit answers it and you never see the question.
+- **Desktop notices: Turn on always answers.** It says when the browser is asking, explains how to allow notices
+  when the browser stays silent (for example in Arc), and sends one test notice.
+- **A ticket a teammate deleted** shows "Deleted by <owner>" with **Remove from my board**.
+- **A chat message sent during Claude's usage limit waits** and is answered when the squad carries on.
+- **On a phone**, the banners fold into one slim row while a ticket is open, and the website's docs pages fit.
+
 ## [1.1.1] — 2026-11-03
 
 A security update. Nothing changes in how squad-kit works.
@@ -886,7 +1141,9 @@ First public release.
 - Plan-generation meta-prompt (`generate-plan.md`), intake template (`intake.md`), and plan skeleton reference (`story-skeleton.md`).
 - Documentation: `docs/philosophy.md`, `docs/getting-started.md`, `docs/customization.md`, `docs/vs-spec-kit.md`.
 
-[Unreleased]: https://github.com/AzmSquad/squad-kit/compare/v1.1.1...HEAD
+[Unreleased]: https://github.com/AzmSquad/squad-kit/compare/v1.2.1...HEAD
+[1.2.1]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.2.1
+[1.2.0]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.2.0
 [1.1.1]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.1.1
 [1.1.0]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.1.0
 [1.0.1]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.0.1

package/README.md

@@ -1,6 +1,10 @@
 <p align="center">
   <a href="https://squad-kit.com">
-    <img src="https://squad-kit.com/logo-wordmark.svg?v=2" alt="squad-kit logo" width="360">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://squad-kit.com/readme/header-dark.png">
+      <source media="(prefers-color-scheme: light)" srcset="https://squad-kit.com/readme/header-light.png">
+      <img src="https://squad-kit.com/readme/header-light.png" alt="squad-kit: Your AI Engineering Squad. One Unified Harness." width="800">
+    </picture>
   </a>
 </p>
 
@@ -11,8 +15,6 @@
   <a href="https://squad-kit.com"><img src="https://img.shields.io/badge/site-squad--kit.com-7cffa0?labelColor=0a0a0c" alt="Website"></a>
 </p>
 
-**Your AI Engineering Squad. One Unified Harness.**
-
 squad-kit is an agent harness for the whole software cycle. You describe what you need in plain words. A
 squad of AI agents takes it from that ask to a release: the Analyst, the Architect, the Builder, the Tester
 and the Reviewer. You stay in control. The squad asks you when it needs you, and nothing important moves on
@@ -34,8 +36,10 @@ without your approval.
 4. The Architect writes the **design**: the decision and the steps. You, or a developer, approve it.
 5. The Builder writes the code in its own copy of the project. Your own folder stays as it is.
 6. squad-kit runs the tests, lint and build itself. The Reviewer checks the work with fresh eyes. The Tester
-   takes a screenshot for each "done when".
-7. You check this **proof** and press **Looks right**.
+   shows each "done when" in one or more screenshots, one per part or case, taken with squad-kit's own browser.
+7. You check this **proof**: each "done when" says **Met**, **Not working yet**, **Not shown yet** or **Not on a
+   screen**. **Where to look** names the pages, and **Try it yourself** runs the ticket's own copy of the app, with
+   nothing merged. Then press **Looks right**.
 8. You press **Release**. squad-kit writes the changelog, sets the version and adds the git tag.
 
 When the squad needs you, a banner shows on every page with the button to press, the browser tab shows how many
@@ -50,6 +54,10 @@ terminal command, so developers can do the same from the terminal.
   AI tool the squad runs on. squad-kit uses your existing sign-in, so there is nothing new to buy. squad-kit
   also finds Codex, but cannot run it yet.
 
+There is nothing else to install. squad-kit installs its own browser for the screenshots the first time it needs
+one, so there is no `npx playwright` to run. **Windows** works, but it is less protected and not fully tested yet:
+use it on projects you trust.
+
 ## Install
 
 ```bash
@@ -84,14 +92,16 @@ Any folder works:
 
 | The folder | What squad-kit does |
 | --- | --- |
-| An empty folder | Makes a new git repo. The Architect picks the stack with you on your first ticket. |
+| An empty folder | Makes a new git repo and asks "What do you want to build?". The Architect picks the technology when your first ticket is planned, and squad-kit finds how to test and run it after the first build. |
 | Code with git | Keeps your repo and its history as they are. |
 | Code without git | Makes a repo, with your files in its first commit. Generated folders like `node_modules` and `dist`, and `.env` files, stay out. |
 | A folder with several code repos | Works across them. Each ticket works in one repo. |
 | A squad-kit 0.x project | Keeps your stories, plans and tracker settings. Moves your sign-ins to this computer. |
 
-Then the Architect reads the project, which takes a few minutes. It maps the code and finds how to install,
-test, build and run it. You can follow it on the board.
+Then a setup page shows each step live while the Architect reads the project, finds how to test and run it, and
+squad-kit tries the tests and opens the app once. It takes a few minutes, and you can leave the page. Then the
+**Overview** opens: what the project is, who uses it, how its parts fit, the rules found, and ideas for a first
+ticket. Approve it with **Looks right, start working**, and the squad follows those rules.
 
 ## Your first ticket
 
@@ -112,10 +122,26 @@ The step-by-step guide is in [Getting started](docs/getting-started.md).
 - **A slow step says so**, with what it is doing and three ways out: **Give it 10 more minutes**, **Stop and try
   again**, or **Stop**. A step that makes no progress says what squad-kit checked.
 - **Run your app** from **Your apps** in the sidebar: Start, Open, Restart and Stop, from squad-kit's own copy of
-  `main`. After **Looks right**, **Run the new version** shows the change. Terminal: `squad app start`.
+  `main`. If another program holds its port, it moves to a free one by itself. After **Looks right**, **Run the new
+  version** shows the change. Terminal: `squad app start`.
+- **Tickets that need each other**: when a design depends on a ticket that is not merged yet, it waits with
+  **Build on its branch**, **Build anyway** or **Wait**.
 - **Remove a ticket** you no longer want with **Delete**, and take finished ones off the board with **Archive**.
   The dialog lists what goes and what stays; the cost stays in Usage. Terminal: `squad delete`, `squad archive`.
 
+## Checks you can trust
+
+- **Not checked, never a fake pass**: a project with no tests shows "Not checked" in orange.
+- **Weakened tests stop the ticket**: deleted or skipped tests, fewer tests, or a changed test setup.
+- **Proof is checked**: each screenshot must be a real, new picture, and squad-kit's own check looks at all the
+  pictures of each "done when" together before it says **Met**.
+- **The Builder works in a sandbox** where the computer allows it: its copy only, no keys or `.env` files, and only
+  the package registries and websites you allow.
+- **The project's own commands run in a guard** on Mac and Linux: the tests, the setup and the app work normally, but
+  can't read your keys, your sign-ins or squad-kit's own files.
+- **Agents get fixed tools, no free commands**, for screenshots, the app and the checks. squad-kit checks each
+  request and does the job itself.
+
 ## When something goes wrong
 
 - **Every stop says what happened, what is safe, and the ways out**, as buttons: Try again, Fix it yourself,
@@ -165,19 +191,29 @@ Hand over and clones work for a project whose `.squad/` sits in its one code rep
 
 ## Talk to the squad
 
-Open a chat with any agent on a ticket. **Asking never stops the work**: the squad keeps working while you
-talk. To change what gets built, press **Propose a change**. The Analyst writes the change into the spec, old
+**Ask a question** is at the top of every ticket, in every state: working, in the queue, waiting for another ticket,
+stopped, at review, taken over or released. Whoever knows the ticket best answers: the Analyst before the build, the
+Builder during and after it, the Tester once there are screenshots. It answers questions only, like "how do I test
+this?" or "where is the new page?", and the ticket stays exactly where it is. Terminal: `squad chat <ticket> --ask`.
+
+You can also open a chat with any agent on a ticket. **Asking never stops the work**: the squad keeps working while
+you talk. To change what gets built, press **Propose a change**. The Analyst writes the change into the spec, old
 and new side by side, and you approve it. A released ticket answers questions only. A change to it becomes a new
 linked ticket or a bug report.
 
+**The squad asks you only about the business.** Technical questions stay with the agent and squad-kit. Nobody may ask
+you for a password or a key, to change squad-kit's settings, or to change git history: squad-kit refuses it and
+writes one line in the ticket's activity.
+
 ## Cost and models
 
 - squad-kit picks a **model level** for each role and step from the project's **Quality** setting: **Best**
   (the default) builds and reviews on the strongest model, **Balanced** builds on it at medium effort, and
   **Thrifty** builds on a lighter one. **Fast** stays for screenshots and small helpers. The team or each person
   can change single steps on the **Squad and AI** page.
-- The board shows **what each ticket and each role used**, in tokens and in money at the AI company's API
-  prices. Your own AI subscription pays for it. This shows where the cost goes.
+- The board shows **what each ticket and each role used**, the way you pay. On a Claude subscription it says the
+  work is included in your plan, and shows its size and its value at API prices (a value, not a bill). With an API
+  key it shows real dollars, against a budget per ticket and per month.
 - One **limit of tickets at once** (2 by default, up to 5) is shared by all your projects, because they use the
   same AI account.
 
@@ -186,6 +222,8 @@ linked ticket or a bug report.
 - [Getting started](docs/getting-started.md): your first hour, from install to a release.
 - [Moving to 1.0](docs/migrating-to-1.0.md): from squad-kit 0.x, and from early 1.0 boards.
 - [The app](docs/console.md): Home, the board, the ticket drawer, Squad and AI, and Settings.
+- [From a BRD to a built product](docs/requirements.md): upload a requirements document, approve the breakdown,
+  send it to Azure DevOps and let the squad build it.
 - [CHANGELOG](CHANGELOG.md): what changed in each version.
 
 The 0.x planner commands (`squad new-story`, `squad new-plan`, `squad auth` and others) still ship. Their docs

package/SECURITY.md

@@ -7,8 +7,8 @@ or `squad upgrade`.
 
 | Version | Supported |
 | ------- | --------- |
-| 1.1.x   | ✅        |
-| < 1.1   | ❌        |
+| 1.2.x   | ✅        |
+| < 1.2   | ❌        |
 
 ## Reporting a vulnerability
 
@@ -33,7 +33,8 @@ Credit will be given in the release notes unless you prefer to remain anonymous.
 ## How squad-kit keeps you safe
 
 - **The app runs on your computer only.** It listens on `127.0.0.1`, behind a private link with a token kept in
-  `~/.squad-kit/app.json`. Nothing is hosted.
+  `~/.squad-kit/app.json`. Nothing is hosted. It answers only at its own address (Host and Origin are checked on every
+  route), and a token in a link works for reads only.
 - **Sign-ins stay on this computer.** Tracker tokens and keys live in `~/.squad-kit/projects/<id>/secrets.yaml`
   (mode `0600` on POSIX), never in the project folder or in git. A project moved from 0.x has its
   `.squad/secrets.yaml` moved there once. To run your app, squad-kit copies your project's `.env` files into its own
@@ -44,6 +45,29 @@ Credit will be given in the release notes unless you prefer to remain anonymous.
   own copy of the code, the Tester cannot change code, and no agent may change the instruction files the next session
   would follow, squad-kit's own `.squad/` folder, or git history. squad-kit checks after each step and puts back what
   an agent changed outside its lane. Text from trackers and pasted messages reaches agents as data, never as orders.
+- **Agents get fixed tools, no free commands.** For screenshots, the app and the checks, an agent presses one of
+  squad-kit's tools. squad-kit checks every field, does the job itself, and refuses and logs what breaks a check.
+- **The project's own commands run in a guard** on Mac and Linux: the tests, setup, the app and the release pipeline
+  can't read your keys, sign-ins, browser profiles, squad-kit's own folder or the `.env` files in your project folder.
+  They can't change the copy's link to git or git's own folder either, so nothing they write can make squad-kit's own
+  git, which runs outside the guard, start a program of theirs.
+- **The project's commit hooks run in the same guard, once, on a stand-in.** They look at the change on a branch of
+  their own, so a hook cannot move a real branch, plant a hook, change a git setting or reach another ticket. The real
+  commit is made after, outside the guard, with your signature if your git signs.
+  **Known gap, being closed next:** while they run, hooks share git's store of objects, so a hook built to do harm could
+  change a file stored there. A project with no commit hooks is not affected.
+- **squad-kit runs no other hook.** Every other git it runs has hooks off: it does not run a project's `pre-push`,
+  `post-merge`, `post-checkout` or `post-commit` outside that one commit (a `post-commit` runs on the stand-in). The
+  project's own checks have already run in the guard by then. Pushing from your own terminal still runs your hooks.
+  A project that uses Git LFS still gets its large files uploaded: a push runs squad-kit's own small `pre-push`, kept in
+  its own folder, which does only that.
+- **squad-kit's git starts nothing a repo names by itself:** no file monitor (`core.fsmonitor`), no diff program
+  (`diff.external`, textconv), and it never looks inside a nested repo. Programs named in your own git settings for the
+  network, credentials, filters and merges stay on (`core.sshCommand`, git-lfs): they need a line in a settings file,
+  and neither the guard nor an agent's sandbox can write those files.
+- **Windows is less protected and not fully tested yet.** There, the agents' own commands and the project's own
+  commands have no guard, so they can reach other files on the computer, squad-kit's own too. Use it on projects you
+  trust. Settings says so.
 - **The engine owns git and the release.** Agents never merge, push or grade their own work.
 - **The npm package is built and published by GitHub Actions** from a release tag, with npm trusted publishing (no
   npm token exists) and a signed provenance statement you can check on npmjs.com.