@jawache/flow 0.1.1 → 0.2.1

package/README.md

@@ -70,7 +70,7 @@ flow init — created:
   + .githooks/pre-commit
   + .flow/ — flow's own state, self-ignoring, never committed
   + node_modules/@jawache/flow → …/flow (a link to the flow that is running — nothing here resolved @jawache/flow)
-  + ~/.claude/settings.json — SessionStart · PreToolUse · PostToolUse · Stop
+  + ~/.claude/settings.json — SessionStart · PreToolUse · PostToolUse · PostToolUseFailure · Stop
   + git config core.hooksPath .githooks
   next: `flow status` — what is bound, and what is not wired yet.
 ```
@@ -83,7 +83,7 @@ Six things, and each one is checkable:
 | `.githooks/pre-commit` | the commit gate. Never written over one you already have |
 | `.flow/` | flow's own state and logs. It ignores itself, so your `.gitignore` is untouched |
 | `node_modules/@jawache/flow` | a link to the flow that is running, because this folder resolves no `@jawache/flow` of its own. `npm i -D @jawache/flow` and this row disappears |
-| the host's `settings.json` | four hook registrations, so a coding agent in any repo asks flow first |
+| the host's `settings.json` | five hook registrations, so a coding agent in any repo asks flow first |
 | `core.hooksPath` | what makes git run the gate. It is per-clone, so every fresh checkout runs `flow init` |
 
 `flow init --empty` gives you the same wiring with no opinions, for a repo that knows what it wants.
@@ -103,7 +103,7 @@ flow is ON — 4 guardrails · 2 breadcrumbs, every one resolved and able to fir
   categories subagent — what the entries below bind to
   session
     🍞 flow.orientation
-        This repo is guarded by flow. Guardrails block risky edits before they land (and again at commit); …
+        This repo is guarded by flow. Guardrails are rules that refuse a change, and every change to the fi…
   touch
     🍞 flow.editingTheGuardrails  —  on flow.config.ts .claude/settings.json .claude/settings.local.json .claude/agents/** .claude/skills/**
         You are editing the guardrails themselves. If this edit weakens, disables or removes a guardrail or…
@@ -121,7 +121,7 @@ flow is ON — 4 guardrails · 2 breadcrumbs, every one resolved and able to fir
   ✓ config: /tmp/flow-demo/flow.config.ts
   ✓ commit-gate: .githooks/pre-commit runs `flow commit` over the staged set
   ✓ hooks-path: core.hooksPath = .githooks
-  ✓ hooks: ~/.claude/settings.json — SessionStart · PreToolUse · PostToolUse · Stop
+  ✓ hooks: ~/.claude/settings.json — SessionStart · PreToolUse · PostToolUse · PostToolUseFailure · Stop
 green — every rule loads, every fitting is in place.
 ```
 
@@ -140,7 +140,13 @@ orientation breadcrumb is injected into the session as context, before the agent
 **2 — a banned command is refused.** Ask the agent to force-push the branch. It is stopped
 *before the command runs*, with the rule's own sentence, and there is no way around it.
 
-**3 — the commit gate holds.** Have the agent write a file containing the literal marker
+**3 — a shell edit is refused too.** Ask the agent to add a `TODO` to a guarded file with a
+heredoc or `sed -i` instead of the Edit tool. The write goes through, so the file on disk changes.
+The same rule then checks it, and flow puts the file back to the content it had before. The refusal
+is printed beside the command's own output. Notice that a refused write never stays, whichever tool
+made it.
+
+**4 — the commit gate holds.** Have the agent write a file containing the literal marker
 `DO`-`NOT`-`COMMIT` (spelled whole), stage it, and commit. Git refuses at the hook, naming the rule
 and the file. Take the marker out and the same commit lands.
 
@@ -238,9 +244,9 @@ Six things to know, and then you can write your own:
 | moment | when | guardrail | breadcrumb |
 | --- | --- | --- | --- |
 | `session` | a chat starts, resumes, or is compacted | — | ✓ |
-| `touch` | a tool call names a file | — | ✓ |
-| `write` | a file is about to be written | ✓ | — |
-| `delete` | a command is about to remove a file | ✓ | — |
+| `touch` | a tool call names a file, or a shell command reads a file | — | ✓ |
+| `write` | a file is created or changed. A write from the Edit tool is checked before the file changes; a write from a shell command is checked the moment it has changed. A refused write is undone | ✓ | — |
+| `delete` | a file is removed. An `rm` is checked before it runs; any other removal is checked the moment the file is gone. A refused delete puts the file back | ✓ | — |
 | `command` | a shell command is about to run | ✓ | — |
 | `commit` | git's pre-commit hook, over the staged set | ✓ | — |
 | `turn-end` | the agent is about to hand back | ✓ | — |
@@ -301,7 +307,7 @@ flow guards itself: `flow.config.ts` at the root binds the ten packs above throu
 `guards/house.ts`. A door that stops exporting, a rule that stops loading or a bundle that stops
 building refuses this repo's own next commit first.
 
-Longer documentation is in [`docs/user/`](docs/user/index.html): the guidebook, the five-minute
+Longer documentation is in [`docs/user/`](docs/user/index.md): the guidebook, the five-minute
 quick start, the config reference, how to author a pack, and one page per stock check.
 
 ## Licence