squad-kit 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -7,6 +7,123 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.2] — 2026-11-05
+
+A patch about the guard. It closes what a review of 1.2.1 found open, moves commit hooks to a throwaway git folder, and says
+plainly what the guard is and is not. Nothing changes in how you work with the squad.
+
+### What the guard promises
+
+- **1.2.1 and earlier promised too much.** The guard stops accidents and most bad behaviour, but it is not a wall against
+  code built on purpose to break out. `SECURITY.md` now says what it stops and what it does not. Use squad-kit on projects and
+  tickets you trust, read what the Builder changes, and use squad-kit's sign-ins, not keys exported in a shell.
+- **It closes more.** A command can no longer move its copy or the folders above git's own. It can no longer write in
+  all of `~/.cache` or `~/Library/Caches`, where your own tools run programs from. On a Mac it can no longer signal other
+  programs, or swap the guard's rules for a later command. A `.env` in your own checkout stays hidden, and so do sockets
+  under `~/.ssh` and `~/.gnupg` and the keys into a runtime's virtual machine. On Linux the guard ran for real for the first
+  time: a `.env` is hidden 3 folders down, and a socket behind `/var/run` no longer stops every command.
+- **A project's own browsers still work.** Playwright gets a folder with the copy, with the browsers this computer has already
+  linked in, so `playwright install` no longer waits on a read-only folder. Puppeteer and Electron download to the copy's
+  cache. On a Mac, Puppeteer's Chrome needs `args: ['--no-sandbox']`, as it did before: its own sandbox cannot start inside
+  the guard. Cypress gets a card until an engineer allows its folder.
+
+### The guard and Docker
+
+- **The project's own commands can no longer reach Docker.** In 1.2.0 and 1.2.1, a command in the guard could connect to
+  Docker's socket, start a container with a hidden folder mounted in it, and read what the guard hides. Now the sockets of
+  Docker Desktop, colima, lima, Rancher Desktop, OrbStack, Finch and Podman are refused, and on a Mac so is Docker's own
+  port on this computer. On Linux that port stays open.
+- **A project whose tests talk to Docker directly now gets a refusal** until a person allows it. The card says Docker is
+  not open to the project's own commands, in a check, a setup or an app's start, and an engineer can allow its socket's
+  folder in Settings.
+
+### The project's commit hooks
+
+- **They run on a throwaway git folder.** squad-kit makes it outside the project for each run, and on Mac and Linux the real
+  git folder is now read only to them, all of it. Only the files in the copy and the commit's words come back, and
+  squad-kit stages the files itself and makes the real commit from those. So **what a hook staged counts for nothing**: a
+  file it force-adds stays out if git ignores it, a file it takes out of the commit goes back in, and a report file it
+  leaves goes in.
+- **The limits 1.2.1 listed are gone.** A hook sees your branch by its real name, not a stand-in's. lint-staged's backup
+  stays out of your `git stash list`, even when a Stop cuts it off. A hook can no longer change a file in git's store of
+  objects.
+- **A Stop, a hook that runs out of time and a crash** put the files back as they were staged and remove new ones. What was
+  on disk then is kept in `refs/squad/on-disk/<ticket>`, so no work is lost half-way through a formatter.
+- **A hook's folder has only the repo's filters of its settings.** A hook that needs a remote, or fetches, gets the usual card
+  with **Save without this check**.
+- **What a hook leaves in its group ends when the commit does**, or at the next start after a crash.
+- **A hook's "no" on a merge being finished holds.** Try again runs the hook again, instead of passing it by.
+
+## [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
@@ -1071,7 +1188,8 @@ 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.2.0...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

package/README.md

@@ -138,7 +138,9 @@ The step-by-step guide is in [Getting started](docs/getting-started.md).
 - **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.
+  can't read the usual places for keys and sign-ins, or squad-kit's own files. The guard stops accidents and most bad
+  behaviour. It is not a wall against code built on purpose to break out, so use squad-kit on projects you trust and read
+  what the Builder changes.
 - **Agents get fixed tools, no free commands**, for screenshots, the app and the checks. squad-kit checks each
   request and does the job itself.
 

package/SECURITY.md

@@ -33,12 +33,13 @@ 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
   copy of the code in `~/.squad-kit/projects/<id>/apps/` (mode `0600`), never anywhere else.
-- **Agents never see your secrets.** No agent may read squad-kit's secret files, and the commands squad-kit runs for
+- **Agents are kept from your secrets.** No agent may read squad-kit's secret files, and the commands squad-kit runs for
   you (tests, setup and release) start without the AI and tracker keys.
 - **Agents stay in their lane.** Every step runs with the permissions it needs and no more: the Builder edits only its
   own copy of the code, the Tester cannot change code, and no agent may change the instruction files the next session
@@ -46,11 +47,57 @@ Credit will be given in the release notes unless you prefer to remain anonymous.
   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.
-- **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 project's own commands run in a guard** on Mac and Linux: the tests, setup, the app, the release pipeline and the
+  commit hooks. **The guard stops accidents and most bad behaviour, but it is not a wall against code built on purpose to
+  break out.** On a Mac its rules start from allowing everything and block a list. Use squad-kit on projects and tickets you
+  trust, and read what the Builder changes.
+
+  What it stops:
+  - Reading the usual places for keys and sign-ins (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.azure`, `~/.kube`, `~/.docker`, the
+    GitHub and cloud sign-ins, the keys into a runtime's virtual machine, an `.npmrc` with a token), browser profiles and
+    squad-kit's own folder. A place it does not know about is not hidden.
+  - Reading the `.env` files in your project folder. On a Mac, all of them. On Linux, the ones it finds 3 folders down when
+    a command starts, outside folders such as `node_modules`.
+  - Writing outside its copy, the proof folder, the temp folder and the package caches. `~/.cache` and
+    `~/Library/Caches` stay read only: your own tools run programs from there. The copy cannot be moved, and git's own
+    folder cannot be changed or moved, so nothing written there can make squad-kit's own git start a program.
+  - Reaching a container runtime. A container can mount any folder, so a command that reaches Docker could read everything
+    above. Connections to the sockets of Docker Desktop, colima, lima, Rancher Desktop, OrbStack, Finch and Podman are
+    refused where the guard knows them. A runtime that listens somewhere else is not covered. **1.2.0 and 1.2.1 did not
+    have this**: there, a command could read hidden files through Docker when Docker was running. If a project's own tests
+    need Docker, an engineer can allow its socket's folder in Settings, knowing that this opens what the guard hides.
+  - Signalling other programs. On a Mac a signal reaches only what the command started. On Linux other programs are not
+    visible at all.
+
+  What it does not stop:
+  - **The network.** A command can reach the network, so what it can read it can send.
+  - **Other local services.** On a Mac a command can still talk to other services on this computer, and to programs that
+    listen on a local port. On Linux it can reach your session's bus and gpg agent under `/run/user`, and Docker's own port
+    if you turned that on (on a Mac, ports 2375 and 2376 are refused).
+  - **Other programs' environments, on a Mac.** A command can read the environment of your other programs, so keys you
+    exported in a shell can be seen. Use squad-kit's sign-ins, not exported keys.
+  - **An ssh agent.** A command cannot read a key loaded in it, but it can ask the agent to use it.
+  - **What a command leaves running, on a Mac.** A process that leaves its group lives on after the command, with the same
+    guard around it, and can change the copy's files.
+- **The project's commit hooks run once, on a throwaway git folder.** squad-kit makes that folder outside the project for
+  each run. It reads git's store of objects and writes only its own. Its settings are squad-kit's, with your branch by its
+  real name and the repo's own filters, which run only in the guard. On Mac and Linux the real git folder stays read only to
+  the hooks, all of it: objects, branches, settings, the stash and the hooks. Only two things come out: the files in the
+  copy and the commit's words. squad-kit's own git then stages the files and makes the real commit, outside the guard, with
+  your signature if your git signs. So nothing a hook puts in its git folder reaches the real store, and squad-kit's git
+  never reads a setting a hook wrote. The folder goes after each run, and at the next start after a crash. A hook that
+  reaches past it to the real folder can read there, and its writes are refused.
+- **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 throwaway folder). 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 has no guard and is not fully tested yet.** There, the agents' own commands and the project's own commands
+  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.