@jawache/flow 0.2.1 → 0.3.0

package/docs/user/migrations/0.1.0.md

@@ -0,0 +1,142 @@
+---
+summary: "upgrade to 0.1.0 from a checkout linked with `npm link`"
+---
+
+# Upgrade to 0.1.0
+
+[All guides](./index.md)
+
+0.1.0 is the first release published to npm. Before it, a repo ran flow from a clone of the flow repository, linked with `npm link`. This page moves a repo from such a checkout to the published package, and covers what changed in the packs before the release: the `guard` pack is renamed `flow`, some checks left `@jawache/flow/packs`, and some pack entries were removed or renamed. The hook registrations, `.githooks/pre-commit` and the CLI commands are the same as in the checkout.
+
+## 1 · Install 0.1.0
+
+Replace the link with the published package. Keep `flow` on PATH: the hook registrations and `.githooks/pre-commit` run it by name.
+
+```sh
+npm unlink -g @jawache/flow
+npm i -g @jawache/flow@0.1.0    # puts `flow` on PATH
+npm i -D @jawache/flow@0.1.0    # in a repo with a package.json: pins the version in its lockfile
+```
+
+Commit `package.json` and the lockfile together. If the repo binds the `node` pack, the commit message needs a line `new-dep: @jawache/flow — <why>`, or `node.newDependencyNeedsReason` refuses the commit.
+
+`flow status` does not check that `flow` is on PATH. Without it, the session hooks fail with nothing blocked, and `.githooks/pre-commit` refuses every commit.
+
+## 2 · Required changes
+
+### 2.1 · Rename the `guard` pack to `flow`
+
+**Applies if:** `grep -rnE '\bguard\b' flow.config.ts` (and your own pack files) prints an import or a binding of `guard`. After the install, `flow status` exits 2 with `does not provide an export named 'guard'`.
+
+**Change:**
+
+```ts
+// before
+import { guard } from "@jawache/flow/packs";
+pack(guard, { packs: ["./guards/house.ts"] })
+override(guard.someEntry)
+// after
+import { flow } from "@jawache/flow/packs";
+pack(flow, { packs: ["./guards/house.ts"] })
+override(flow.someEntry)
+```
+
+`packs` is required. `[]` is a valid value. Leaving it out refuses with `missing-parameter`.
+
+**Why:** the pack that protects the guard itself is named after the product.
+
+### 2.2 · Replace checks removed from `@jawache/flow/packs`
+
+**Applies if:** this prints a line:
+
+```sh
+grep -rnE 'conventionalCommit|noGitDiscard|noHandEditedVersion|justfileDocs|lockfileInStep|newCommandNeedsCaller|\bSurface\b' flow.config.ts <your pack files>
+```
+
+**Change:** for `conventionalCommit`, `noGitDiscard` and `noHandEditedVersion`, bind the `git` pack. For `justfileDocs`, bind the `justfile` pack. For `lockfileInStep`, bind the `node` pack. Each pack includes the rule. To keep a rule without its pack, copy the check into your own pack.
+
+Replace `newCommandNeedsCaller` with `commitReason` from `@jawache/flow`. Its regex patterns are now listed in the binding, one capture group each:
+
+```ts
+// before
+newCommandNeedsCaller({ surfaces: [{ file: "flow.ts", known: ["test", "hook"] }], token: "new-verb:" })
+// after
+commitReason({
+  diffAdds: [{ file: "flow.ts", patterns: ['command\\s*===\\s*"([a-z][a-z-]*)"'], known: ["test", "hook"] }],
+  token: "new-verb:",
+})
+```
+
+The old check matched three patterns without listing them: `'case\\s+"([a-z][a-z-]*)"\\s*:'`, `'command\\s*===\\s*"([a-z][a-z-]*)"'` and `'sub\\s*===\\s*"([a-z][a-z-]*)"'`. List the ones your surface uses. A test case that records the diff changes its key from `"git diff HEAD -- flow.ts"` to `"diff HEAD -- 'flow.ts'"`.
+
+**Why:** a check lives in the pack that uses it, or in the grammar when more than one does.
+
+### 2.3 · Remove or rename overrides of entries that are gone
+
+**Applies if:** this prints a line:
+
+```sh
+grep -rnE 'override\((fcis\.(noLogicInTypesOrIndex|strictLayout)|typescript\.(tsconfigFromBase|eslintFromBase)|secrets\.dxSeam)' flow.config.ts <your pack files>
+```
+
+After the install, `flow status` reports `unknown-entry` and the config does not load.
+
+**Change:**
+
+- `fcis.noLogicInTypesOrIndex`, `fcis.strictLayout` and `secrets.dxSeam` are removed: delete their overrides.
+- `typescript.tsconfigFromBase` is now `typescript.tsconfigStrict`: rename the override.
+- `typescript.eslintFromBase` exists only when the `typescript` pack is given `eslintBase` (2.4).
+
+### 2.4 · Name your base files to the `typescript` pack
+
+**Applies if:** the repo has a `tsconfig.base.json` or an `eslint.config.base.js` that its other configs extend.
+
+**Change:**
+
+```ts
+// before
+pack(typescript, { typecheck, lint })
+// after
+pack(typescript, { typecheck, lint, tsconfigBase: "tsconfig.base.json", eslintBase: "./eslint.config.base.js" })
+```
+
+**Why:** the pack no longer assumes base files exist. Without these two settings it does not check that every config extends them.
+
+### 2.5 · Remove `names` from the `secrets` pack
+
+**Applies if:** `pack(secrets, { … names: … })` appears in the config.
+
+**Change:** delete `names:`. It is ignored at run time and is a type error in the editor. `dx` and `encrypt` are now optional and default to dotenvx.
+
+## 3 · What now blocks or passes differently
+
+- **`flow.editingTheGuardrails` is shown for Claude Code settings too:** `.claude/settings.json`, `.claude/settings.local.json`, `.claude/agents/**` and `.claude/skills/**`. Pass `hostSurface: []` to the `flow` pack to turn this off.
+- **`git.noGitDiscard` refuses more:** a bare `git checkout <tracked path>` is refused, not only the form with `--`. With `cd X && git …` or `git -C X`, it checks repo `X`.
+- **`git.noForcePush` matches only a real command**, so the words in prose or a heredoc no longer trip it.
+- **`flow status` exits 2 for every config that does not load.** A config the grammar refused used to exit 1. Check any script that tells the two apart.
+- **While the grammar refuses the config, the agent may still write the config and its pack files** to fix it, and the turn can end. Every write used to be refused.
+- **A CommonJS repo loads its config.** A `package.json` with `"type": "commonjs"`, or with no `type`, used to fail with `Cannot use import statement outside a module`.
+- **`node.dependencies` watches all five lockfiles.**
+
+## 4 · Optional
+
+New pack parameters, all with defaults:
+
+- `docs`: `root`, `allow`
+- `tdd`: `tests`
+- `fcis`: `sibling`, `tests`
+- `git`: `versionFile`, `types`
+- `justfile`: `tools`, and `recipes`, which turns on the new `justfile.useTheRecipe` entry
+- `secrets`: `publicPrefixes`, `localFiles`, `envFiles`, `extraSecretShapes`
+- `typescript`: `strictOptions`
+
+New exports from `@jawache/flow`: `DiffAdds`, `gitDirPrefix`, `escapeRe`, `substitutionInProse` and `SUBSTITUTION_MESSAGE`.
+
+## 5 · Verify
+
+```sh
+command -v flow && flow --version    # prints a path, then 0.1.0
+flow status                          # green
+flow test                            # every case green
+flow commit $(git ls-files --cached --others --exclude-standard)    # exit 0
+```

package/docs/user/migrations/0.1.1.md

@@ -0,0 +1,44 @@
+---
+summary: "upgrade to 0.1.1 from 0.1.0"
+---
+
+# Upgrade to 0.1.1
+
+[All guides](./index.md)
+
+0.1.1 adds two things a config can use: its own ast-grep grammar, and a breadcrumb shown before a shell command. No changes are needed: no pack changed, nothing was removed from the exports, and the hook registrations and `.githooks/pre-commit` are the same as in 0.1.0.
+
+## 1 · Install 0.1.1
+
+```sh
+npm i -D @jawache/flow@0.1.1    # when flow is a dev dependency of the repo
+npm i -g @jawache/flow@0.1.1    # when `flow` is installed globally
+```
+
+## 2 · Required changes
+
+None.
+
+## 3 · What now blocks or passes differently
+
+Nothing.
+
+## 4 · Optional
+
+- **Declare an ast-grep grammar** for a language with no published grammar package, such as astro, vue or svelte. Pass it in the second argument to `defineConfig`:
+
+  ```ts
+  export default defineConfig([pack(house)], {
+    grammars: [{ name: "astro", libraryPath: "grammars/astro.dylib", extensions: ["astro"] }],
+  });
+  ```
+
+  `flow status` then prints a `grammars` line. If the library file is missing, that line is red, and every rule on that language refuses.
+- **Show a note before a shell command runs:** `breadcrumb().at(command).on("npm install*", "npm i *").text("…")`. `.on(…)` matches the command line. Without `.on(…)` the note is shown on every shell command. It uses the existing `PreToolUse` registration, so `flow init` does not need to run again.
+
+## 5 · Verify
+
+```sh
+flow status    # green
+flow test      # every case green
+```

package/docs/user/migrations/0.1.2.md

@@ -0,0 +1,58 @@
+---
+summary: "upgrade to 0.1.2 from 0.1.1"
+---
+
+# Upgrade to 0.1.2
+
+[All guides](./index.md)
+
+0.1.2 refuses a `depcruise` layer written as a regex, and lets a layer leave holes in itself. Only a repo with its own `depcruise` rule is affected: no shipped pack uses `depcruise`. The exports, the hook registrations and `.githooks/pre-commit` are the same as in 0.1.1.
+
+## 1 · Install 0.1.2
+
+```sh
+npm i -D @jawache/flow@0.1.2    # when flow is a dev dependency of the repo
+npm i -g @jawache/flow@0.1.2    # when `flow` is installed globally
+```
+
+## 2 · Required changes
+
+### 2.1 · Rewrite a `depcruise` layer written as a regex
+
+**Applies if:** after the install, `flow status` exits 2 and `flow test` fails, both reporting `bad-check-options` with the layer and the entry. To find them before you install, search the `layers:` of your own `depcruise` rules for an entry that starts with `^`, contains `(?` or `|`, or ends with `$`:
+
+```sh
+grep -rnE '"\^|\(\?|\||\$"' flow.config.ts <your pack files>
+```
+
+While the config does not load, flow refuses every write except a write that fixes the config.
+
+**Change:** write the layer as globs. A part the layer must leave out goes in `not`:
+
+```ts
+// before
+layers: { pages: ["^src/pages/(?!app/|admin/)"] }
+// after
+layers: { pages: { path: ["src/pages/**"], not: ["src/pages/app/**", "src/pages/admin/**"] } }
+```
+
+**Why:** a layer is a list of globs. In 0.1.1, a regex was read as literal text, so the fence loaded and reported itself armed but matched no file.
+
+Two more refusals arrive with this: a layer with a `not` list cannot be listed in another layer's `only`, and `not: ["node:*"]` is refused.
+
+## 3 · What now blocks or passes differently
+
+A fence that used to match nothing starts to work once its layers are globs. A commit that crosses it, and passed in 0.1.1, is now refused.
+
+## 4 · Optional
+
+- **Leave holes in a layer** with `{ path: [...], not: [...] }`, the new `Layer` type.
+- **Report unusable options from your own check:** `withFaults` and `faultsOf`, exported from `@jawache/flow`, turn a check's own complaint about its options into a load refusal.
+
+## 5 · Verify
+
+```sh
+flow status    # green
+flow test      # every case green
+flow commit $(git ls-files --cached --others --exclude-standard)    # exit 0, or the fence refusals in section 3
+```

package/docs/user/migrations/0.2.0.md

@@ -0,0 +1,113 @@
+---
+summary: "upgrade to 0.2.0 from 0.1.2"
+---
+
+# Upgrade to 0.2.0
+
+[All guides](./index.md)
+
+0.2.0 makes flow judge every change a tool call makes to the tree, not only the changes the Edit and Write tools make. A change a shell command, an MCP tool or a subagent makes is checked after it lands, and a refused change is put back. The hook registrations change to make that work, so every repo re-runs `flow init`. A repo that overrides `docs.noMarkdownInUserDocs` must remove the override, and a repo with its own `banCommands` rule about heredoc text must set `matchHeredocs: true`.
+
+## 1 · Install 0.2.0
+
+```sh
+npm i -D @jawache/flow@0.2.0    # when flow is a dev dependency of the repo
+npm i -g @jawache/flow@0.2.0    # when `flow` is installed globally
+```
+
+## 2 · Required changes
+
+### 2.1 · Re-run `flow init` to update the hook registrations
+
+**Applies if:** after the install, `flow status` prints a red `hooks:` line that says one or both of these:
+
+- `does not call flow for PostToolUseFailure — re-run flow init`
+- `calls flow for PostToolUse on some tools only — an older flow registered it that way`
+
+Every repo upgrading from 0.1.2 has both.
+
+**Change:** run `flow init` in the repo. It keeps the existing `flow.config.ts` and `.githooks/pre-commit`. In the Claude Code settings file it widens the `PostToolUse` registration to every tool, and adds `PostToolUseFailure`. The settings file is the user-level one, `~/.claude/settings.json`, or `$CLAUDE_CONFIG_DIR/settings.json` when that variable is set. It is not the repo's `.claude/settings.json`. Afterwards flow's five registrations are:
+
+```json
+"SessionStart":       [{ "matcher": "startup|resume|clear|compact", "hooks": [{ "type": "command", "command": "flow hook session-start" }] }],
+"PreToolUse":         [{ "matcher": "*", "hooks": [{ "type": "command", "command": "flow hook pre-tool-use" }] }],
+"PostToolUse":        [{ "matcher": "*", "hooks": [{ "type": "command", "command": "flow hook post-tool-use" }] }],
+"PostToolUseFailure": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "flow hook post-tool-use-failure" }] }],
+"Stop":               [{ "hooks": [{ "type": "command", "command": "flow hook stop" }] }]
+```
+
+If the settings file does not parse (a comment or a trailing comma), `flow init` writes nothing to it and says so. Fix the JSON and run `flow init` again.
+
+Restart any Claude Code session that was open during the upgrade. A tool call that started under the old version prints one `flow — could not see what this call changed` message when it finishes.
+
+**Why:** flow now takes a snapshot of the tree before every tool call and compares it after, so it needs the after-call hook for every tool, including calls that fail.
+
+### 2.2 · Remove any override of `docs.noMarkdownInUserDocs`
+
+**Applies if:** `grep -rn "noMarkdownInUserDocs" flow.config.ts` (and your own pack files) prints a line. After the install, `flow status` reports `unknown-entry` for it, and the config does not load. While it does not load, flow refuses every write except a write that fixes the config.
+
+**Change:** delete the `override(docs.noMarkdownInUserDocs)` line. The `docs` pack no longer refuses markdown under `docs/user/`. To keep refusing it, add the entry to your own pack. This is the entry 0.1.2 shipped, with a shorter message:
+
+```ts
+noMarkdownInUserDocs: guardrail()
+  .at(write, commit)
+  .on("docs/user/**/*.md", "docs/user/**/*.mdx")
+  .check(protectedPath({}))
+  .message("User docs are HTML. Markdown belongs in docs/agent/.")
+  .test({ block: [{ path: "docs/user/guide.md", content: "# hi" }] }),
+```
+
+**Why:** user docs may now be markdown. A repo that bound `docs` without an override loses the refusal with no error.
+
+### 2.3 · Set `matchHeredocs: true` on a `banCommands` rule about heredoc text
+
+**Applies if:** the repo has its own `banCommands` rule whose patterns must match text a command is fed through a heredoc, such as a commit message. `flow test` reports a failing `block` case where the banned text appears only inside a heredoc.
+
+**Change:**
+
+```ts
+// before
+banCommands({ ban: ["…"] })
+// after
+banCommands({ ban: ["…"], matchHeredocs: true })
+```
+
+**Why:** `banCommands` now leaves heredoc bodies out of the text it matches, so a script that only contains the words of a banned command is not refused. A heredoc fed to a shell (`bash`, `sh`, `zsh` or `eval`) is still matched. The shipped `git.noAiAttributionInCommits` and both `noShellSubstitutionInProse` entries already set it.
+
+### 2.4 · Clear a red `snapshot:` line
+
+**Applies if:** `flow status` prints a red `snapshot:` line saying a rule `guards <path>, which git ignores`.
+
+**Change:** list the path's glob in `snapshotInclude`, the second argument to `defineConfig`, or narrow the rule with `.on(…)` or `.ignore(…)`:
+
+```ts
+export default defineConfig([pack(house)], { snapshotInclude: [".env"] });
+```
+
+**Why:** the snapshot records the files git lists, tracked or untracked, so a shell write to a path git ignores is never detected unless `snapshotInclude` lists it. `secrets.envEncrypted` on a gitignored `.env` file is the usual case.
+
+## 3 · What now blocks or passes differently
+
+- **Shell commands, MCP tools and subagents are checked.** A write or delete rule now runs on a change any tool call makes: a heredoc, `sed -i`, a script, a formatter, a code generator, `npm install`. A refused file is put back, under `flow — write reverted after it landed` or `flow — delete reverted after it landed`. If a rule refuses generated output or a tool's own files, narrow it with `.ignore(…)`. Keep build output, logs and caches in paths git ignores.
+- **A background command's later writes are judged.** A write a background process makes after its tool call returns is judged by the next tool call and put back if refused.
+- **`rm x && cat > x` is judged as a write** of `x`, not only as a delete.
+- **`banCommands` leaves heredoc bodies out** unless the rule sets `matchHeredocs: true` (2.3). The shipped force-push ban, the justfile recipe map and the work pack's rules now let heredoc text through.
+- **A heredoc is the commit message only when the commit reads standard input**, with `-F -` or `--file=-`. `commitReason` and the git pack's message rules no longer check `git commit <<EOF` without `-F -`. Commit with `git commit -F - <<'EOF'`.
+- **A breadcrumb is shown for a file a shell command reads.** `cat`, `head`, `sed -n`, `grep`, `rg`, `find`, `ls`, `<` and a git pathspec count as reads, and the note is shown before the command runs. A refused command shows no notes.
+- **A folder that is not a git checkout is refused on every tool call**, because flow has nothing to take a snapshot with. Run `git init`, or remove `flow.config.ts` from a folder that is not a repo.
+- **`flow status` and `flow facts` read transcripts from `$CLAUDE_CONFIG_DIR/projects`** when that variable is set.
+- **Shipped text changed:** the `flow` pack's orientation note, and the `docs` pack's messages, which now say user docs may be HTML or markdown.
+
+## 4 · Optional
+
+- **Let only named agents write:** `oneWriter({ writers: [...] })` refuses a write or delete by a session that has none of the listed categories. `pack(work, { writers: ["builder", "parent"] })` turns it on for the `work` pack. Test cases accept `actor: [...]`.
+- **Choose what a refusal puts back:** `defineConfig([...], { revert: "all" })` puts back every file the refused call changed. The default, `"refused"`, puts back only the refused files.
+- **`flow status`** shows the live session's permission mode. **`flow facts`** counts shell reads and writes, and calls per mode.
+
+## 5 · Verify
+
+```sh
+flow status    # green, with: ✓ hooks: … SessionStart · PreToolUse · PostToolUse · PostToolUseFailure · Stop
+flow test      # every case green
+flow commit $(git ls-files --cached --others --exclude-standard)    # exit 0
+```

package/docs/user/migrations/0.2.1.md

@@ -0,0 +1,41 @@
+---
+summary: "upgrade to 0.2.1 from 0.2.0"
+---
+
+# Upgrade to 0.2.1
+
+[All guides](./index.md)
+
+0.2.1 rewords two breadcrumbs in the `justfile` pack. No changes are needed: the config, the exports, the hook registrations and `.githooks/pre-commit` are the same as in 0.2.0.
+
+## 1 · Install 0.2.1
+
+```sh
+npm i -D @jawache/flow@0.2.1    # when flow is a dev dependency of the repo
+npm i -g @jawache/flow@0.2.1    # when `flow` is installed globally
+```
+
+## 2 · Required changes
+
+None.
+
+## 3 · What now blocks or passes differently
+
+Nothing blocks or passes differently. Two breadcrumb texts changed, and a breadcrumb is a note that never refuses anything:
+
+- **`justfile.orientation`**, shown at `session`, now says a script earns a recipe only when it is run regularly, across tasks. It used to say that anything a person should also run becomes a recipe.
+- **`justfile.toolsHome`**, shown at `touch` on the tools folder, now lists a seed and a release's data step as one-offs that get no recipe.
+
+A repo that binds `pack(justfile, …)` without overriding these two entries shows the new text. An agent may now argue against adding a recipe for a one-off script.
+
+## 4 · Optional
+
+- If the repo added recipes for one-off scripts (a seed, a backfill, a data fix), remove those recipes from the justfile and keep the scripts.
+- If the repo overrode `justfile.orientation` or `justfile.toolsHome` only to work around the old wording, remove the override.
+
+## 5 · Verify
+
+```sh
+flow status    # green
+flow test      # every case green
+```

package/docs/user/migrations/0.2.2.md

@@ -0,0 +1,104 @@
+---
+summary: "upgrade to 0.2.2 from 0.2.1"
+---
+
+# Upgrade to 0.2.2
+
+[All guides](./index.md)
+
+0.2.2 changes how the commit gate gets its list of files. The pre-commit hook now runs `flow hook commit` and passes nothing, and flow reads from git the files the commit adds, changes and deletes. A rule bound at both `deletion` and `commit` now also runs on each file a commit deletes, and on the old path of a renamed file. `protectedPath({ existingOnly: true })` now treats a file as new when it was not there before the change. One change is required: the line in `.githooks/pre-commit` that runs `flow commit`.
+
+## 1 · Install 0.2.2
+
+```sh
+npm i -D @jawache/flow@0.2.2    # when flow is a dev dependency of the repo
+npm i -g @jawache/flow@0.2.2    # when `flow` is installed globally
+```
+
+`npm ls @jawache/flow` and `npm ls -g @jawache/flow` show which of the two the repo uses. The hook registrations and `.githooks/pre-commit` run the `flow` that is on PATH.
+
+## 2 · Required changes
+
+### 2.1 · Make the pre-commit hook run `flow hook commit`
+
+**Applies if:** `grep -n "flow commit" .githooks/pre-commit` prints a line. After the install, `flow status` also prints:
+
+```text
+  ✗ commit-gate: .githooks/pre-commit calls the old `flow commit`, which leaves every deleted file unchecked — replace its `flow commit …` line with `exec flow hook commit`.
+```
+
+**Change:** edit the file. Do not delete it: the `flow` pack refuses a delete of `.githooks/pre-commit`. The hook `flow init` wrote before 0.2.2 ends with these lines:
+
+```sh
+staged=$(git diff --cached --name-only --diff-filter=ACMR)
+[ -z "$staged" ] && exit 0
+# shellcheck disable=SC2086
+exec flow commit $staged
+```
+
+Replace all four with one line:
+
+```sh
+exec flow hook commit
+```
+
+If the hook runs other commands as well, keep them, and put `exec flow hook commit` last.
+
+**Why:** the old lines pass flow a list that leaves out deleted files, and they exit before flow runs when a commit only deletes files. `flow commit` still works in 0.2.2, so nothing breaks before you make this change, but deletions are not checked until you do.
+
+### 2.2 · Replace any other command that runs `flow commit` with a file list
+
+**Applies if:** `git grep -n "flow commit" -- ':!.githooks/pre-commit'` prints a line, for example a justfile recipe or a CI step.
+
+**Change:** `flow commit <files…>` now ignores its file list and checks the staged changes. A command that checked a list of files on purpose checks the staged changes instead, which is usually fewer files. To check every file in the repo, use `--all`:
+
+```sh
+# before
+flow commit $(git ls-files --cached --others --exclude-standard)
+# after
+flow hook commit --all
+```
+
+**Why:** git is now the one source of the file list. `flow hook commit` refuses a file list, and `flow commit` ignores one.
+
+## 3 · What now blocks or passes differently
+
+- **A rule bound at both `deletion` and `commit` now runs on each file a commit deletes.** It is called with the file as a delete (`ctx.moment` is `delete`), with the content the last commit has. A rename is a deletion of the old path plus an added file, so the rule runs on the old path. For example, `protectedPath` bound with `.at(write, deletion, commit)` now refuses a commit that deletes or renames a file it protects. In 0.2.1 that commit passed. If a commit is now refused for this, keep the file, or change the rule.
+- **A rule bound at `commit` alone is not called with deleted files.** It checks only the files the commit will contain, as before.
+- **`protectedPath({ existingOnly: true })` lets a shell command add a new file.** In 0.2.0 and 0.2.1, a new file that a shell command created was reverted with the append-only message. Now it is kept. At commit, a file is new when the last commit does not have it. In 0.2.1, every staged file counted as existing, so a rule bound at `commit` refused every new file.
+- **A config that does not load refuses every commit, including one with nothing staged.** The old hook exited before flow ran when nothing was staged.
+
+## 4 · Optional
+
+- **Refuse a deleted or renamed file at commit as well.** Bind an append-only rule at all three moments:
+
+  ```ts
+  appendOnly: guardrail()
+    .at(write, deletion, commit)
+    .on("migrations/**")
+    .check(protectedPath({ existingOnly: true }))
+    .message("A migration already written is history — add a new one instead.")
+    .test({
+      pass: [
+        { path: "migrations/002.sql", content: "new" },
+        { staged: ["migrations/002.sql"], added: ["migrations/002.sql"], world: { fs: { "migrations/002.sql": "new" } } },
+      ],
+      block: [
+        { path: "migrations/001.sql", content: "edited", world: { fs: { "migrations/001.sql": "old" } } },
+        { staged: ["migrations/001.sql"], added: [], world: { fs: { "migrations/001.sql": "edited" } } },
+        { staged: [], deleted: { "migrations/001.sql": "old" } },
+      ],
+    }),
+  ```
+
+- **Read `ctx.file.existed` in your own checks.** It is `true` or `false` for a change a shell command made, and for a file at commit. See the [`ctx` reference](../reference/ctx.md).
+- **Test cases accept three new keys:** `existed` on a `{ path, content }` case, and `added` and `deleted` on a `{ staged }` case. See [Cases](../reference/config.md#cases).
+- **`flow hook commit --all`** runs the commit gate over every file git lists, tracked or not, as if all of them were staged.
+
+## 5 · Verify
+
+```sh
+flow status               # green, with: ✓ commit-gate: .githooks/pre-commit runs `flow hook commit` over the staged changes
+flow test                 # every case green
+flow hook commit --all    # exit 0, or only the refusals section 3 describes
+```

package/docs/user/migrations/0.2.3.md

@@ -0,0 +1,42 @@
+---
+summary: "upgrade to 0.2.3 from 0.2.2"
+---
+
+# Upgrade to 0.2.3
+
+[All guides](./index.md)
+
+0.2.3 widens `git.noAiAttributionInCommits`, the `git` pack's rule against crediting Claude or Anthropic in a commit. It now also reads a commit made with git's own options before `commit`, such as `git -C <dir> commit`. No changes are needed.
+
+## 1 · Install 0.2.3
+
+```sh
+npm i -D @jawache/flow@0.2.3    # when flow is a dev dependency of the repo
+npm i -g @jawache/flow@0.2.3    # when `flow` is installed globally
+```
+
+## 2 · Required changes
+
+None.
+
+## 3 · What now blocks or passes differently
+
+`git.noAiAttributionInCommits` now refuses a commit command that has git options between `git` and `commit` and credits Claude or Anthropic in its message: `git -C <dir> commit …`, `git -c key=value commit …` and `git --git-dir=… commit …`. An agent working in a git worktree often commits with `git -C`, and those commits passed in 0.2.2. If one is now refused, remove the `Co-Authored-By` line, the "Generated with Claude" line or the Claude Code link from the message, and commit again.
+
+## 4 · Optional
+
+- **Bind the `git` pack, if the repo does not.** `git.noAiAttributionInCommits` is in the `git` pack, so a repo that binds only other packs has no rule against the credit line. Add the binding, with the command that cuts a release in your repo:
+
+  ```ts
+  pack(git, { release: "just release" }),
+  ```
+
+  The `git` pack also checks that every commit header is a Conventional Commits header. If the repo's headers use a type outside the default list, such as `review:`, pass the `types` parameter. It replaces the default list, so list every type the repo uses.
+
+## 5 · Verify
+
+```sh
+flow status               # green
+flow test                 # every case green
+flow hook commit --all    # exit 0
+```