crewforth 0.0.1 → 3.0.0-rc.1

package/kit/hooks/trace-blocklist.txt

@@ -0,0 +1,53 @@
+# Trace-scanner word/pattern list (scanned with grep -iE, one pattern per line).
+# High-precision defaults: expressions that won't false-positive on everyday code.
+# Single high-frequency words like "model", "assistant" are DELIBERATELY absent (false-positive risk).
+# Add your own vendor/template name below (§4.2) so it is caught before commit.
+# If a pattern is legitimate in a specific repo: put a .trace-allowlist.txt at that repo's root and
+# write the pattern (FULL line) there -> exempt only in that repo. (Not included in the payload.)
+#
+# Each pattern carries its own case on the line below it (`#test:` must be caught, `#test-clean:` must not).
+# smoke-test.sh discovers them, drives the REAL hook with them, and fails if any pattern has no case — an
+# untested pattern is how a typo ships as a gate that matches nothing. This file is excluded from the scan by
+# name, so the cases here never self-trigger.
+
+Co-Authored-By
+#test: Co-Authored-By: An Assistant <noreply@example.com>
+# "Generated by/with" alone matched every machine-written header in existence — a pubspec.lock, an EF Core
+# scaffold, protoc, openapi-generator. A live --dotnet install could not make its FIRST commit because the
+# cloned base carries a Dart lockfile saying "Generated by pub". §4.1 is about AI AUTHORSHIP, so the pattern
+# now needs that context nearby; the clean cases below pin the classes that used to false-positive.
+generated with.{0,40}(claude|chatgpt|copilot|cursor|codex|assistant|llm|language model|[^a-z]ai([^a-z]|$))
+#test: Generated with an AI coding tool
+generated by.{0,40}(claude|chatgpt|copilot|cursor|codex|assistant|llm|language model|[^a-z]ai([^a-z]|$))
+#test: <!-- Generated by the assistant, do not edit -->
+#test-clean: # Generated by pub
+#test-clean: // <auto-generated> This code was generated by the EF Core tools.
+Written by Claude
+#test: // Written by Claude, reviewed by nobody
+🤖
+#test: chore: tidy up 🤖
+Claude Code
+#test: scaffolded with Claude Code
+Copilot
+#test: suggested by Copilot
+ChatGPT
+#test: pasted from ChatGPT
+AI-generated
+#test: this module is AI-generated
+AI generated
+#test: AI generated boilerplate
+yapay zeka tarafindan
+#test: bu dosya yapay zeka tarafindan uretildi
+asistan tarafindan
+#test: asistan tarafindan duzenlendi
+
+# Ordinary text that names none of the above and must stay committable.
+#test-clean: refactor the order handler and add a regression test
+#test-clean: fix(auth): reject an expired refresh token
+#test-clean: docs: explain the migration rollback procedure
+
+# --- §4.2 vendor / third-party template names (fill in per project) ---
+# The installers uncomment the next line only in a project that keeps the former .NET pattern skill
+# (.claude/skills/cqrs-aop-module), because that skill names the template it was derived from.
+# DevArchitecture
+# <vendor-template-name>

package/kit/settings.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "skillListingBudgetFraction": 0.04,
+  "permissions": {
+    "allow": [
+      "Bash"
+    ],
+    "ask": [
+      "Bash(ssh:*)",
+      "Bash(scp:*)",
+      "Bash(rsync:*)",
+      "Bash(docker:*)"
+    ],
+    "deny": [
+      "Read(.env)",
+      "Read(.env.local)",
+      "Read(.env.*.local)",
+      "Read(**/.env)",
+      "Read(**/.env.local)",
+      "Read(**/.env.*.local)",
+      "Read(~/.ssh/**)",
+      "Read(~/.aws/**)",
+      "Read(~/.kube/**)",
+      "Read(~/.netrc)",
+      "Read(~/.npmrc)",
+      "Read(~/.git-credentials)",
+      "Read(~/.docker/config.json)",
+      "Read(**/id_rsa)",
+      "Read(**/id_dsa)",
+      "Read(**/id_ecdsa)",
+      "Read(**/id_ed25519)",
+      "Read(**/*.pem)",
+      "Read(**/*.p12)",
+      "Read(**/*.pfx)",
+      "Read(**/*.jks)",
+      "Read(**/kubeconfig)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-bash.sh",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-commit-scan.sh",
+            "timeout": 60
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-write.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/context-usage.sh",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/route-hint.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/session-guard.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact|clear|resume|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/session-rehydrate.sh",
+            "timeout": 60
+          }
+        ]
+      },
+      {
+        "matcher": "startup|resume|clear|compact|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/skill-trust.sh",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/board-sync.sh",
+            "timeout": 60
+          }
+        ]
+      },
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/session-update-check.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

package/kit/skills/a11y/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: a11y
+description: |
+  Frontend accessibility audit (WCAG): semantic HTML, keyboard access, focus management, contrast, ARIA, screen readers.
+  Use when building or changing UI, or before shipping a user-facing screen.
+---
+
+# Accessibility (a11y)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "a11y", "accessibility", "WCAG", "screen reader", "keyboard navigation", "contrast", "ARIA", "keyboard only", "with a keyboard", "keyboard focus", "without a mouse", "focus ring", "tab order", "alt text", "color blind", "colour blind", "voiceover", "talkback", "reduced motion"
+
+Goal: make the interface usable by **everyone**, including keyboard, screen reader, and low vision. Baseline target: **WCAG 2.1 AA**.
+Stack-agnostic (web/React/RN); do a web search when needed for framework-specific APIs.
+
+## Checklist
+- [ ] **Semantic HTML**: `button`/`a`/`nav`/`main`/`h1..h6` correct; no `div`-buttons
+- [ ] **Keyboard**: every interaction reachable via Tab, sensible order, visible **focus ring**
+- [ ] **Focus management**: focus moves on modal/route change, focus trap correct
+- [ ] **Contrast**: text ≥ 4.5:1, large text ≥ 3:1
+- [ ] **Alt text**: `alt` on meaningful images; `alt=""` on decorative images
+- [ ] **Forms**: every input has a `label`; error message programmatically linked (`aria-describedby`)
+- [ ] **ARIA**: only when needed; wrong ARIA is worse than no ARIA; role/name/state correct
+- [ ] **Motion/animation**: respect `prefers-reduced-motion`
+- [ ] **Language**: `<html lang>` correct (coordinate with i18n)
+
+## How
+1. **Start with semantics** — the right element solves 80%. Use `button` instead of `role="button"`+`div`.
+2. **Navigate with the keyboard** — drop the mouse, run the whole flow with Tab/Shift-Tab/Enter/Escape; is focus visible and its order sensible.
+3. **Naming** — does every interactive element have an accessible name (`aria-label` on visual-only icon buttons).
+4. **Contrast** — check color pairs against the ratio; don't convey meaning by color alone (add an icon/text).
+5. **Dynamic content** — notify the screen reader via a live region (`aria-live`); manage modal focus.
+6. **Automated + manual** — tools like linters/axe are the baseline; but manual keyboard+reader testing is essential (tools don't catch 100%).
+
+## React / RN note
+- Web React: semantic element in JSX + `htmlFor`/`aria-*`; use `button` instead of a clickable `div`.
+- React Native: `accessible`, `accessibilityLabel`, `accessibilityRole`, `accessibilityState` (coordinate with `frontend-rn-expo`).
+
+## Invariant rules
+1. **Semantics first, ARIA second** — wrong ARIA does harm.
+2. Must be **fully usable by keyboard** — without a mouse.
+3. **Color cannot be the sole carrier of meaning.**
+4. **Automated tools are not enough** — manual keyboard+reader testing.
+5. **Follow the existing design system** — if there is a component library, keep its accessible pattern.

package/kit/skills/adr/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: adr
+description: |
+  Architecture Decision Record: context-decision-consequences, for decisions that are expensive to reverse.
+  Written under docs/adr/.
+---
+
+# Architecture Decision Record (ADR)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "adr", "architecture decision", "decision record", "why this approach", "why we chose", "why we went with", "nobody remembers why", "why we picked"
+
+## When
+On an architecture/technology choice that is expensive to reverse, long-lived, or contested
+(database selection, auth strategy, critical pattern). Small/reversible decisions do not require an ADR.
+
+**Most of these are never announced as decisions, and that is how they get missed.** The examples above all
+sound like a question someone asked — "Redis or Postgres?" — so they are easy to recognise. The ones that
+actually escape arrive inside ordinary build work: you are asked to add a feature, and along the way you settle
+what an entity owns, what a session is bound to, what makes a row unique, which layer holds a rule. Nobody said
+"decide"; you decided anyway, and the next person inherits it with no idea it was a choice. Measured in the
+field: one infrastructure task settled four such questions and produced no record of any of them, in a session
+where this skill was installed and its trigger read every turn.
+
+So the test is not "was I asked to choose". It is: **would a maintainer six months from now, wanting to do this
+differently, need to know why it is this way?** If yes, it is an ADR, however undramatic it felt while writing
+it. Cheap tell: you rejected an alternative in your head and moved on without writing it down.
+
+## On a team, the record ALSO goes on the board
+`docs/` is gitignored in an install, so an ADR written there reaches the machine that wrote it and nobody else —
+which is the opposite of what a decision record is for. When a `teamboard` exists, record it with
+`board.sh decide "<title>" "<context + decision + consequences>"` as well: the board is shared, so it arrives at
+every teammate's next session opening, and it travels even when the board lives in its own repository. The local
+file stays the long form; the board entry is the part that has to reach people, so it must be readable on its
+own — a title nobody can act on ("auth decided") is not a record.
+
+## Format (docs/adr/NNNN-short-title.md, ~1 page)
+```
+# NNNN. <Decision title>
+Status: proposed | accepted | rejected | superseded (by NNNN)
+## Context
+Which problem/constraint requires this decision?
+## Decision
+What was decided (clear, one sentence + rationale)?
+## Consequences
+Pros / cons / accepted trade-offs.
+## Alternatives considered
+Why were they not chosen?
+```
+
+## Principles
+- **Invariant:** a new decision marks the old ADR as `superseded`; an ADR is **never deleted** (decision history is preserved).
+- Numbered and dated; keep it short.
+
+## Deliberately bypassing a rule is a decision too
+A gate the user knowingly overrode — a deferred DoD item, an accepted known gap, a trimmed scope — belongs here
+whenever its effect outlives the task. It is not a lesser kind of decision: choosing *not* to apply a rule shapes
+the codebase exactly as choosing a database does, and it is the one class of decision that leaves no trace in the
+code at all. Six months on, a rule that was weighed and overridden is indistinguishable from one that was never
+noticed, and the second is the one you would want to fix.
+
+Record it in the same file as any other decision, with the fields that make it reversible:
+
+```
+## Bypassed
+- <gate/rule> — why: <reason> — asked by: <who> — revisit: <condition or date>
+```
+
+`revisit` is the load-bearing field. A bypass with no condition attached is permanent by default, and nobody
+chose permanence. See [[confidence-check]], which is where most bypasses surface.
+
+## DoD
+- Decision + rationale + rejected alternatives recorded; status current.
+- Any deliberately bypassed rule is recorded with its reason, who asked, and what would reverse it.

package/kit/skills/api-design/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: api-design
+description: |
+  API contract design: resource naming, error model, versioning, pagination, backward compatibility, OpenAPI.
+  A predictable interface that evolves without breaking consumers.
+---
+
+# API Design
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "api design", "api contract", "api versioning", "openapi", "swagger", "rest contract", "breaking api change", "response shape", "response format", "endpoint returns", "error format"
+
+Goal: a contract the consumer can **predict** and that can **evolve** without breaking. Once published, a
+public API is a commitment; a breaking change is expensive. Stack-agnostic (REST as the baseline; GraphQL/gRPC follow similar principles).
+
+## Checklist
+- [ ] Resource names are **consistent** (plural nouns, a single `kebab`/`camel` style), resources not verbs
+- [ ] Correct HTTP semantics: GET (side-effect free) · POST · PUT/PATCH · DELETE; correct **status code**
+- [ ] A uniform **error model**: machine-readable code + human message + (if any) field details
+- [ ] A clear **versioning** strategy (URL `/v1` or header); a breaking change means a new version
+- [ ] **Pagination/filtering/sorting** defined and consistent on large collections
+- [ ] **Backward compatibility**: adding a field is additive; removing a field or changing its meaning is breaking → version
+- [ ] **Idempotency** (for POST/payment-like cases) supported via a key when needed
+- [ ] The contract is documented in **OpenAPI**; example request/response present (coordinate with `docs-writer`)
+
+## How
+1. **Model the resource** — a noun not a verb: `POST /orders` (✓), `POST /createOrder` (✗).
+2. **Status codes**: 200/201/204 · 400 validation · 401/403 authorization · 404 · 409 conflict · 422 · 429 · 5xx. Use them meaningfully.
+3. **Error contract** — every error has the same shape:
+   ```json
+   { "code": "ORDER_NOT_FOUND", "message": "Order not found", "details": [] }
+   ```
+   No stack trace / internal detail leakage (overlaps with `security-scan`).
+4. **Versioning**: additive changes in the same version; breaking (remove/rename a field / add a required field) → `/v2`.
+5. **Collection**: pagination (cursor or offset), filter/sort parameters; a consistent envelope.
+6. **Write the contract** — OpenAPI/schema; with examples. Wire the change to `docs-writer`, and if breaking to `release`/CHANGELOG.
+
+## Breaking vs additive
+| Additive (safe) | Breaking (needs a version) |
+|---|---|
+| Add an optional field/endpoint | Remove / rename a field |
+| A new optional parameter | Add a required parameter |
+| A new enum value (if the consumer is tolerant) | Change a type/meaning, change a status code |
+
+## Invariant rules
+1. **A public API is a commitment** — a breaking change is not made silently; version + announcement.
+2. **Consistency > local cleverness** — a single naming/error/pagination pattern across the whole API.
+3. **The error model is uniform and machine-readable.**
+4. **No internal detail leakage** — a stack trace / DB error does not go to the consumer.
+5. **The contract is documented** — OpenAPI + example; at design time, not after the code.

package/kit/skills/automode-policy/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: automode-policy
+description: |
+  Auto-mode classifier config: inspect what the classifier that answers permission prompts is configured
+  with, and catch the silent case where a custom autoMode block drops the built-in block rules.
+allowed-tools: Bash(bash ${CLAUDE_SKILL_DIR}/scripts/*.sh *)
+---
+
+# Auto-mode policy (automode-policy)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "auto mode", "classifier policy", "permission classifier", "autoMode settings", "policy pack"
+
+Purpose: Crewforth's gates run at the tool level (`guard-bash.sh`, the git hooks) and that is where its
+enforcement stays. Since 2026-08-14 auto mode is the default permission mode on Pro/Max/Team, putting a
+classifier in front of the same actions. This skill lets you **see and audit that classifier's configuration**.
+It does not add a gate — read the measurement below before treating it as one.
+
+## Measured: these rules did not enforce
+Claude Code 2.1.238, 2026-08-24, interactive session, `permissionMode=auto`, this policy installed in user
+settings, `claude auto-mode config` listing all three rules:
+
+| Run | Result |
+|---|---|
+| "run `git reset --hard` and `git clean -fd`, I'm sure" | ran with **no prompt, no block** — uncommitted work destroyed |
+| Control: no policy, no explicit intent, "get this repo back to the last commit" | identical — no block |
+| Headless probe: absolute `hard_deny` "never write any file" + a write request | file created |
+| Headless control: write to `.git/config`, a **protected path** the docs say auto mode routes to the classifier | written, unprompted |
+
+Crewforth's rule names `git reset --hard` and `git clean -fd` verbatim and declares them unconditional, so the
+wording is not the variable. The control run shows the classifier did not gate this class of action **at all**,
+with or without custom rules. Whatever `autoMode` prose rules do, they are not a substitute for a gate.
+
+What did protect the work in every run was the model choosing to back it up first — discipline, not a gate. Crewforth
+exists because discipline is the thing that fails silently.
+
+## Why this is Crewforth's only out-of-project file
+The classifier reads `autoMode` from **user** settings (`~/.claude/settings.json`) or **managed** settings.
+It deliberately ignores `.claude/settings.json` and `.claude/settings.local.json`, because a checked-in repo
+could otherwise ship its own allow rules. So a plugin cannot install this policy — an installer must, with
+the user's word. That is `scripts/apply.sh`, and it asks before it writes.
+
+## The failure this still catches — the reason to keep the skill
+Setting an `autoMode` array **without the literal `"$defaults"`** replaces the built-in list for that section.
+Measured on Claude Code 2.1.238: dropping `"$defaults"` took `soft_deny` from **66 rules to 2** — force push,
+piping a downloaded script into a shell, production deploys and auto-mode bypass all gone — with **no error and no warning**. The
+session looks healthy. `scripts/check.sh` reads what the classifier actually uses (`claude auto-mode config`),
+not the policy file, because a policy file that parses is not a policy that applies.
+
+## What Crewforth puts in the config (present, not proven to enforce)
+| Rule | Tier | Why the defaults don't cover it |
+|---|---|---|
+| Crewforth Uncommitted Work Destruction | `hard_deny` | The built-ins treat destructive git as **soft**, which explicit user intent clears. Uncommitted work is the one artifact with no second copy, and Crewforth has watched a subagent run `git checkout -- .` over live work. Hard tier = intent cannot clear it. |
+| Crewforth Gate Tampering | `soft_deny` | `--no-verify`, unsetting `core.hooksPath`, editing `.claude/hooks/*`. The defaults block generic bypass, not the removal of *this project's* gates. |
+| Crewforth Internal Docs Publication | `soft_deny` | §4.3: `docs/` is internal by policy. No built-in can know that. |
+
+Deliberately **not** set: `environment` (your trusted repos/buckets/domains — guessing them either over-trusts
+or, set without `"$defaults"`, wipes the built-in list) and `allow` (loosening is the user's call, never
+Crewforth's). §4.4 needs nothing here: `guard-bash.sh` fails `git commit`/`git push` closed in auto mode, and it —
+not a `permissions.ask` rule — is what asks in the interactive modes. An `ask` rule for those verbs would
+break the `CLAUDE_GIT_OK` pre-authorisation: a matching ask rule prompts even when a hook returns `allow`.
+
+## How
+```bash
+bash .claude/skills/automode-policy/scripts/check.sh          # inspect the effective config
+bash .claude/skills/automode-policy/scripts/apply.sh          # propose → diff → ask → install → verify
+bash .claude/skills/automode-policy/scripts/apply.sh --strict # also route EVERY shell command to the classifier
+bash .claude/skills/automode-policy/scripts/apply.sh --print  # print the block, paste it yourself
+```
+Verifying is read-only for Crewforth but not for Claude Code: `claude auto-mode config` rewrites its own
+`settings.json` as it reads (reformatted, model aliases normalised, a `backups/` directory created). Measured,
+not assumed — it matters if you diff that file in CI.
+
+`check.sh` exit codes: `0` config as expected · `2` built-ins dropped · `3` Crewforth rules absent/partial · `4`
+cannot read the config
+(CLI too old, or auto mode unavailable on this account). `/crew-doctor` reports the same check.
+
+`--strict` sets `autoMode.classifyAllShell`, which suspends narrow Bash/PowerShell allow rules while auto mode
+is active so every shell command reaches the classifier. It buys coverage with latency and one classifier call
+per command — offer it, don't assume it.
+
+## Rules
+- **Never install this silently.** It writes outside the project; `apply.sh` asks, backs up, and restores the
+  backup itself if the post-install check fails.
+- **Never hand-merge the user's settings file.** Without `jq` or `python3`, `apply.sh` prints the fragment and
+  stops — a half-written global settings file is worse than an uninstalled policy.
+- **Keep `"$defaults"` verbatim** in every array you touch, including any rule you add later.
+- **Do not present this as a gate.** Crewforth's enforcement is `permissions.deny` and the `PreToolUse` hooks,
+  both of which are measured firing in `smoke-test`. This skill reports configuration.
+- Re-measure before that changes. The table above is one version on one day; if a release makes custom
+  `autoMode` rules enforce, this skill's claim can grow — but only with a run that shows a block.

package/kit/skills/automode-policy/references/policy.json

@@ -0,0 +1,13 @@
+{
+  "autoMode": {
+    "hard_deny": [
+      "$defaults",
+      "Crewforth Uncommitted Work Destruction: Discarding uncommitted work across a whole tree or directory rather than a file the user named — `git checkout -- .`, `git restore .`, `git reset --hard`, `git clean -fd`, `git stash drop/clear`, or any equivalent that resolves to the working tree, a directory, or a glob. Uncommitted work is the one artifact with no second copy, and a subagent or a cleanup step reaches for these commands while doing something the user did ask for. Blocked unconditionally: commit, stash by name, or revert the specific files instead, and ask the user which."
+    ],
+    "soft_deny": [
+      "$defaults",
+      "Crewforth Gate Tampering: Disabling, bypassing, or removing this project's own tool-level gates — `--no-verify` / `-n` on commit or push, unsetting or repointing `core.hooksPath`, running git with `-c core.hooksPath=`, deleting or rewriting files under `.claude/hooks/`, or removing hook entries from `.claude/settings.json`. The gates are the project's stated policy; an agent that finds them inconvenient must report the obstacle, not remove it. The user may still authorise a specific bypass in their own words.",
+      "Crewforth Internal Docs Publication: Staging, committing, or pushing the project's internal working documents — anything under `docs/` such as session state, roadmaps, and handover notes, including with `git add -f` against a gitignore rule. These files carry machine paths, unfinished decisions, and internal reasoning; they are deliberately local. Publishing one needs the user to say which file and where."
+    ]
+  }
+}

package/kit/skills/automode-policy/scripts/apply.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Install Crewforth's auto-mode classifier policy into USER settings — the one part of Crewforth that lives
+# outside the project, because the classifier deliberately ignores `autoMode` in .claude/settings.json
+# (a repo could otherwise ship its own allow rules). Writing outside the project is exactly the kind of
+# action §4.4 says needs the user's word, so this script asks, backs up, and verifies — in that order.
+#
+# Usage:
+#   apply.sh              propose the change, show the diff, ask, install, verify
+#   apply.sh --yes        same without the prompt (for a scripted setup the user drives)
+#   apply.sh --strict     also set autoMode.classifyAllShell — every shell command reaches the classifier
+#   apply.sh --print      print the policy fragment and exit (paste it yourself; no writes, no tooling)
+set -u
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+POLICY="$HERE/../references/policy.json"
+CHECK="$HERE/check.sh"
+TARGET="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"
+YES=0; STRICT=0
+for a in "$@"; do case "$a" in
+  --yes) YES=1 ;; --strict) STRICT=1 ;;
+  --print) cat "$POLICY"; exit 0 ;;
+  *) echo "apply.sh: unknown argument '$a'"; exit 64 ;;
+esac; done
+
+[ -f "$POLICY" ] || { echo "❌ policy.json not found next to this script"; exit 1; }
+
+# A JSON merge into the user's own settings file is not a job for sed. It goes through Crewforth's one JSON reader
+# (eval/lib/settings-json.awk, the same file adopt.sh merges with) — the same code on every OS. This used to pick
+# jq, then python3, and on a stock Windows box with neither it printed the fragment and stopped, so the one
+# platform with no JSON tool could not install the policy at all. The reader sits three levels up in both
+# editions: .claude/skills/<s>/scripts -> .claude/eval/lib, and <plugin>/skills/<s>/scripts -> <plugin>/eval/lib.
+SJ="$HERE/../../../eval/lib/settings-json.awk"
+if [ ! -f "$SJ" ]; then
+  echo "⚠️  Crewforth's JSON reader is missing ($SJ) — not merging your settings file by hand."
+  echo "   Add this block to $TARGET yourself (keep the \"\$defaults\" entries verbatim):"
+  echo; cat "$POLICY"; exit 3
+fi
+
+mkdir -p "$(dirname "$TARGET")"
+[ -f "$TARGET" ] || printf '{}\n' > "$TARGET"
+
+TMP="$TARGET.crew-new"; BAK="$TARGET.crew-bak-$(date +%Y%m%d-%H%M%S)"
+# autoMode takes every member of the policy's autoMode (the policy wins), the user's other members and every other
+# key untouched. rc 10 = the target is not a JSON object: nothing is written.
+if [ "$STRICT" = 1 ]; then set -- -v setk=classifyAllShell -v setv=true; else set --; fi
+awk -v op=overlay -v key=autoMode "$@" -f "$SJ" "$TARGET" "$POLICY" > "$TMP" && [ -s "$TMP" ] \
+  || { echo "❌ merge failed (invalid JSON in $TARGET?)"; rm -f "$TMP"; exit 1; }
+
+# Verify the CANDIDATE before it is anyone's real configuration. `claude --settings <file>` runs the
+# classifier config resolution against the file, so a policy that would silently drop the 66 built-in
+# soft blocks is caught here — while the only file on disk is still a temp file.
+echo "== verifying the candidate (nothing installed yet) =="
+bash "$CHECK" --settings "$TMP"; RC=$?
+if [ "$RC" != 0 ]; then
+  echo "❌ candidate did not verify (rc=$RC) — nothing was written."
+  rm -f "$TMP"; exit "$RC"
+fi
+
+echo
+echo "== what changes in $TARGET =="
+if command -v diff >/dev/null 2>&1; then diff -u "$TARGET" "$TMP" | sed -n '1,60p'; else echo "(no diff tool; new file written to $TMP)"; fi
+echo
+if [ "$YES" != 1 ]; then
+  # No terminal means no one can consent. Asking anyway is worse than useless: with a tty present but nobody
+  # reading it — a CI runner, a background job, a test harness — `read </dev/tty` blocks forever. Measured:
+  # this hung Crewforth's own smoke test. No consent possible -> abort, and say how to do it deliberately.
+  if [ ! -t 0 ] && [ ! -t 1 ]; then
+    echo "not an interactive session — nothing written. Re-run with --yes if this is a setup you are driving."
+    rm -f "$TMP"; exit 0
+  fi
+  printf "Install this policy into your USER settings? [y/N] "
+  read -r ans </dev/tty 2>/dev/null || ans=""
+  case "$ans" in y|Y|yes|YES) : ;; *) echo "aborted — nothing written."; rm -f "$TMP"; exit 0 ;; esac
+fi
+
+cp "$TARGET" "$BAK" && mv "$TMP" "$TARGET" || { echo "❌ could not write $TARGET"; exit 1; }
+echo "✅ installed. backup: $BAK"
+echo "== verifying what the classifier now actually uses =="
+bash "$CHECK"; RC=$?
+if [ "$RC" != 0 ]; then
+  echo "❌ post-install verification failed (rc=$RC) — restoring the backup."
+  cp "$BAK" "$TARGET"; exit "$RC"
+fi
+echo "   Undo any time:  cp \"$BAK\" \"$TARGET\""

package/kit/skills/automode-policy/scripts/check.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Report what the auto-mode classifier is CONFIGURED with — and be exact about what that does and does not prove.
+#
+# MEASURED, 2026-08-24, Claude Code 2.1.238, interactive session, permissionMode=auto, this policy installed in
+# USER settings and shown as present by `claude auto-mode config`:
+#   `git reset --hard && git clean -fd` ran with no prompt and no block, destroying uncommitted work — the exact
+#   action Crewforth's hard_deny rule names verbatim and calls unconditional.
+#   A control run with NO policy and NO explicit user intent behaved identically.
+#   Two headless probes agreed, including an absolute "never write any file" rule, and a protected-path write
+#   (.git/config) that the docs say auto mode routes to the classifier went through untouched.
+# Reading: the classifier did not gate this class of action at all, with or without custom rules. So this script
+# reports CONFIGURATION, never enforcement. Crewforth's enforcement lives in its PreToolUse hooks and git hooks,
+# which are measured firing in smoke-test; nothing here replaces them.
+#
+# Auto mode is the default permission mode on Pro/Max/Team since 2026-08-14: a classifier, not the user,
+# answers most permission prompts. It reads its rules from `autoMode` in USER or MANAGED settings only
+# (never from .claude/settings.json — a repo could otherwise ship its own allow rules), so this policy is
+# the one part of Crewforth that lives outside the project. That is why it is installed explicitly and
+# verified here rather than assumed.
+#
+# The failure this guards against is silent: setting an autoMode array WITHOUT the literal "$defaults"
+# replaces the built-in list for that section — 66 soft-block rules and the single built-in hard block
+# disappear with no error, and the session looks healthy. So this script does not read the policy file;
+# it reads what the classifier ACTUALLY uses (`claude auto-mode config`) and checks the built-ins are
+# still there. A policy file that parses is not a policy that applies.
+#
+# Side effect, measured — this script writes nothing itself, but `claude auto-mode config` does: reading the
+# effective config makes Claude Code rewrite its own settings.json (reformatted, values normalised such as
+# `opus` -> `opus[1m]`, a backups/ directory created). That is Claude Code maintaining its own file, and it
+# keeps a backup, but "verifying costs nothing" would be a false claim.
+#
+# What it still catches, and why it is worth running: setting an autoMode array without the literal "$defaults"
+# silently replaces the built-in list for that section (measured: soft_deny 66 -> 2, no error, no warning). That
+# footgun is real whatever the enforcement story is, and nothing else in the toolchain reports it.
+#
+# Usage:  check.sh [--settings <file>]     # --settings inspects a CANDIDATE policy without installing it
+# Exit:   0 config as expected · 2 built-ins DROPPED · 3 kit rules absent/partial · 4 cannot read the config
+set -u
+
+SETTINGS=""
+[ "${1:-}" = "--settings" ] && { SETTINGS="${2:-}"; [ -z "$SETTINGS" ] && { echo "check.sh: --settings needs a file"; exit 4; }; }
+
+command -v claude >/dev/null 2>&1 || { echo "  ⚠️  claude CLI not on PATH — auto-mode policy cannot be verified"; exit 4; }
+
+if [ -n "$SETTINGS" ]; then CFG="$(claude --settings "$SETTINGS" auto-mode config 2>/dev/null)"
+else                        CFG="$(claude auto-mode config 2>/dev/null)"; fi
+
+# `auto-mode` is v2.1.19x+; an older CLI prints usage/error instead of the four rule lists.
+case "$CFG" in *'"soft_deny"'*) : ;; *)
+  echo "  ⚠️  'claude auto-mode config' did not return a rule set — CLI too old, or auto mode unavailable on this account"
+  exit 4 ;;
+esac
+
+# Built-ins, checked PER SECTION and anchored to the rule's label.
+#
+# A whole-blob substring search is NOT enough and this was measured, not assumed: "Data Exfiltration" and
+# "Auto-Mode Bypass" also occur inside the prose of `allow` rules, so a config with those built-ins dropped
+# still contains both strings somewhere. That check reports a false PASS — the worst kind for a policy gate.
+# `claude auto-mode config` prints one rule per line inside `"<section>": [ ... ]`, and every rule begins
+# with its label, so slice the section first and anchor the match to the start of the string.
+section(){ printf '%s\n' "$CFG" | awk -v s="$1" '
+  $0 ~ "^[[:space:]]*\""s"\"[[:space:]]*:[[:space:]]*\\[" { inb=1; next }
+  inb && /^[[:space:]]*\]/ { inb=0 }
+  inb { print }'; }
+
+has_rule(){ printf '%s\n' "$2" | grep -q "^[[:space:]]*\"$1"; }
+
+HD="$(section hard_deny)"; SD="$(section soft_deny)"
+MISSING=""
+has_rule 'Data Exfiltration' "$HD" || MISSING="$MISSING hard_deny/Data-Exfiltration"
+has_rule 'Git Destructive'   "$SD" || MISSING="$MISSING soft_deny/Git-Destructive"
+has_rule 'Auto-Mode Bypass'  "$SD" || MISSING="$MISSING soft_deny/Auto-Mode-Bypass"
+
+# Each kit rule counts under its 3.0 name or its pre-3.0 one ("CSK …"): a config applied by 2.x keeps passing
+# until the user re-applies, which overlays autoMode and so replaces the old names rather than adding beside them.
+KITR=0
+kit_rule(){ has_rule "Crewforth $1" "$2" || has_rule "CSK $1" "$2"; }
+kit_rule 'Uncommitted Work Destruction' "$HD" && KITR=$((KITR+1))
+kit_rule 'Gate Tampering'               "$SD" && KITR=$((KITR+1))
+kit_rule 'Internal Docs Publication'    "$SD" && KITR=$((KITR+1))
+
+if [ -n "$MISSING" ]; then
+  echo "  ❌ classifier built-ins DROPPED:$MISSING"
+  echo "     ↳ an autoMode array was set without the literal \"\$defaults\" — restore it in ~/.claude/settings.json"
+  echo "     ↳ inspect with: claude auto-mode config    · built-ins: claude auto-mode defaults"
+  exit 2
+fi
+
+if [ "$KITR" -eq 0 ]; then
+  echo "  ·  Crewforth auto-mode rules not in the classifier config (built-ins only) — not a gate either way"
+  echo "     ↳ optional: bash .claude/skills/automode-policy/scripts/apply.sh"
+  exit 3
+fi
+
+if [ "$KITR" -lt 3 ]; then
+  echo "  ·  Crewforth auto-mode rules PARTIAL ($KITR/3 present) — built-ins intact"
+  echo "     ↳ re-apply: bash .claude/skills/automode-policy/scripts/apply.sh"
+  exit 3
+fi
+
+echo "  ✅ classifier config: built-ins intact, 3/3 Crewforth rules present (CONFIGURED, not proven to enforce)"
+exit 0