@cratis/pi 7.100.0 → 7.101.0

package/package/corpus/hooks/README.md

@@ -11,6 +11,7 @@ Three layers:
 | Pattern pass | `PostToolUse` on a write | `scripts/cratis-pattern-scan.sh` | zero tokens until a match | appends a one-line reminder to context, never blocks |
 | Hard block | `PreToolUse` on a write | `scripts/cratis-guard-writes.sh` | zero | exits **2** — the write does not happen |
 | Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-store-mutations.sh` | zero; parses only commands that mention `cratis` | exits **2** — the store-changing `cratis chronicle` command does not run |
+| Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-secrets.sh` | zero; parses only commands that mention a credential-bearing tool or file | exits **2** — a command that prints credentials (full `kubectl` specs and secrets, `env`/`printenv`, `docker inspect`, secret-manager reads, `.env`/kubeconfig/key files) does not run unless it projects a field; see [`secrets.md`](../rules/secrets.md) |
 | Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-pr-body.sh` | fetches shared rules only for `gh pr create/edit` | exits **2** for inline bodies, invalid notes or conflicting release labels; warns and allows when offline with no cache |
 | Cleanup of delivered work | `PostToolUse` on `Bash` (`gh pr merge`, `git pull/merge/worktree`) and `SessionStart` (Pi: `tool_result` and `session_start`) | `scripts/cratis-cleanup-worktrees.sh --hook` | zero when the command is unrelated | never blocks; removes delivered worktrees and branches, reports what it kept |
 | Quality gate (Claude) | `Stop` | `scripts/cratis-quality-gate.sh` | one build/test run, only when relevant files changed | exits **2** — the turn does not end |
@@ -674,6 +675,7 @@ Each is an explicit, auditable opt-out — none of them is a default.
 | `CRATIS_HOOKS_PATTERNS=<path>` | replaces the pattern file |
 | `CRATIS_HOOKS_GATES=<path>` | replaces the gate file (the project override still merges over it) |
 | `CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1` | allows `cratis chronicle` commands that change a live store; set by the person who authorized the mutation, in the environment the harness was started from |
+| `CRATIS_HOOKS_ALLOW_SECRET_READS=1` | allows commands the secrets guard blocks; set by the person who authorized the read, in the environment the harness was started from — an assignment inside the command is ignored |
 | `CRATIS_HOOKS_STORE_MUTATIONS=<path>` | replaces the store-mutation guard's command lists (the `.local.json` beside the script still extends them) |
 | `CRATIS_HOOKS_SUBPATH_REPORT=1` | prints every `@cratis/*` subpath reference and how it resolved, not only the failures |
 | `CRATIS_HOOKS_IMPORT_REPORT=1` | prints every `@cratis/*` named import binding and how it resolved, not only the failures |
@@ -727,6 +729,12 @@ jq -nc '{tool_name:"Bash", tool_input:{command:"cratis chronicle observers repla
 jq -nc '{tool_name:"Bash", tool_input:{command:"cratis chronicle observers list -o plain"}}' \
   | bash .cratis/ai/hooks/scripts/cratis-guard-store-mutations.sh; echo "exit=$?"
 
+# Secrets guard, both directions: expect exit 2, then exit 0 for the projected neighbor
+jq -nc '{tool_name:"Bash", tool_input:{command:"kubectl get pods -o json"}}' \
+  | bash .cratis/ai/hooks/scripts/cratis-guard-secrets.sh; echo "exit=$?"
+jq -nc '{tool_name:"Bash", tool_input:{command:"kubectl get pods -o name"}}' \
+  | bash .cratis/ai/hooks/scripts/cratis-guard-secrets.sh; echo "exit=$?"
+
 # Quality gate — show the dispatch plan without running anything
 jq -nc '{session_id:"t", cwd:"'"$PWD"'", stop_hook_active:false}' \
   | CRATIS_HOOKS_GATE_DRYRUN=1 bash .cratis/ai/hooks/scripts/cratis-quality-gate.sh

package/package/corpus/hooks/scripts/cratis-guard-secrets.sh

@@ -0,0 +1,458 @@
+#!/usr/bin/env bash
+# PreToolUse hook (Bash) — hard block on shell commands that print credentials into the transcript.
+#
+# secrets.md says a credential must never enter an agent transcript, and lists the command classes that
+# print one: full Kubernetes specs and secrets, the process environment, container inspection, secret-manager
+# reads and credential files. This guard is what enforces it: every simple command in the shell command is
+# found (quotes, $( ), backticks, subshells, pipelines, here-documents, `bash -c`, `eval`, `kubectl exec ... --`
+# and `docker exec`, and the wrappers sudo/env/timeout/xargs/rtk are looked through) and classified. A command
+# that only mentions a word inside an argument (echo, rg, grep, git commit -m) is never a finding.
+# Exit 2 blocks the tool call and sends stderr back to the model; every other command exits 0.
+#
+# What it sees is the command text. A credential reached through a variable, an alias, a function, a script
+# file or a pipe into a shell is invisible to it; a projection it cannot see through (`-o jsonpath` that dumps
+# `{.}`) is trusted. See .cratis/ai/hooks/README.md.
+#
+# Escape hatch for a human who authorized the read — set in the environment the agent harness was started
+# from, never inside the command (an assignment in the command is ignored):
+#   CRATIS_HOOKS_ALLOW_SECRET_READS=1
+set -euo pipefail
+
+# SCRIPTDIR, not a path relative to the caller: shellcheck resolves a plain relative `source=`
+# against the current working directory, and these hooks are linted from wherever CI happens to run.
+# shellcheck source=SCRIPTDIR/hook-lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/hook-lib.sh"
+
+[ "${CRATIS_HOOKS_ALLOW_SECRET_READS:-0}" = "1" ] && exit 0
+
+input="$(hook_read_stdin)"
+[ -n "$input" ] || exit 0
+hook_have jq || exit 0
+
+command_text="$(hook_json "$input" '.tool_input.command')"
+[ -n "$command_text" ] || exit 0
+
+# Cheap exit for the overwhelming majority of shell commands, which mention none of these words.
+case "$(printf '%s' "$command_text" | tr '[:upper:]' '[:lower:]')" in
+    *kubectl*|*printenv*|*env*|*docker*|*podman*|*"gh "*|*vault*|*pulumi*|*aws*|*"az "*|*gcloud*|*kubeconfig*|*.kube*|\
+    *export*|*declare*|*typeset*|*id_rsa*|*id_ed25519*|*id_ecdsa*|*id_dsa*|*.pem*|*.p12*|*.pfx*|*token*|*.netrc*|*.npmrc*|\
+    *credentials*|*.pgpass*|*secrets*) ;;
+    *) exit 0 ;;
+esac
+
+IFS= read -r -d '' awk_program <<'AWK' || true
+function report(what, alt) {
+    if (what in seen) return
+    seen[what] = 1
+    printf "%s\t%s\n", what, alt
+}
+function enqueue(text) {
+    if (text == "" || queued >= 64) return
+    queue[++queued] = text
+}
+function base(word) { word = tolower(word); sub(/.*\//, "", word); return word }
+
+# ── tokenizer: splits text into simple commands, queueing nested command text ──
+function flush_word() {
+    if (inword) W[++nw] = word
+    word = ""; inword = 0
+}
+function end_cmd() {
+    flush_word()
+    if (nw > 0) analyze(W, 1, nw)
+    split("", W); nw = 0
+}
+function cmdsub(s, i, n,    start, depth, c, j) {
+    start = i; depth = 1
+    while (i <= n) {
+        c = substr(s, i, 1)
+        if (c == "\\") { i += 2; continue }
+        if (c == "\047") { j = index(substr(s, i + 1), "\047"); if (j == 0) { i = n + 1; break } i += j + 1; continue }
+        if (c == "\"") {
+            i++
+            while (i <= n && substr(s, i, 1) != "\"") { if (substr(s, i, 1) == "\\") i++; i++ }
+            i++; continue
+        }
+        if (c == "(") depth++
+        else if (c == ")") { depth--; if (depth == 0) break }
+        i++
+    }
+    enqueue(substr(s, start, i - start))
+    return i + 1
+}
+function read_heredocs(s, i, n,    h, e, line, cmp, body) {
+    for (h = 1; h <= nheredoc; h++) {
+        body = ""
+        while (i <= n) {
+            e = index(substr(s, i), "\n")
+            if (e == 0) { line = substr(s, i); i = n + 1 } else { line = substr(s, i, e - 1); i += e }
+            cmp = line
+            if (HDDASH[h]) sub(/^\t+/, "", cmp)
+            if (cmp == HD[h]) break
+            body = body line "\n"
+        }
+        if (hd_shell) enqueue(body)
+    }
+    nheredoc = 0; hd_shell = 0
+    return i
+}
+function tokenize(s,    i, n, c, c2, j, dash, delim) {
+    n = length(s); i = 1; nw = 0; word = ""; inword = 0; nheredoc = 0; hd_shell = 0
+    split("", W)
+    while (i <= n) {
+        c = substr(s, i, 1)
+        if (c == "\\") {
+            c2 = substr(s, i + 1, 1)
+            if (c2 == "\n") { i += 2; continue }
+            word = word c2; inword = 1; i += 2; continue
+        }
+        if (c == "\047") {
+            inword = 1
+            j = index(substr(s, i + 1), "\047")
+            if (j == 0) { word = word substr(s, i + 1); i = n + 1; continue }
+            word = word substr(s, i + 1, j - 1); i += j + 1; continue
+        }
+        if (c == "\"") {
+            inword = 1; i++
+            while (i <= n) {
+                c = substr(s, i, 1)
+                if (c == "\\") { word = word substr(s, i + 1, 1); i += 2; continue }
+                if (c == "\"") { i++; break }
+                if (c == "$" && substr(s, i + 1, 1) == "(") { i = cmdsub(s, i + 2, n); word = word "x"; continue }
+                if (c == "`") {
+                    j = index(substr(s, i + 1), "`")
+                    if (j == 0) { i = n + 1; break }
+                    enqueue(substr(s, i + 1, j - 1)); i += j + 1; word = word "x"; continue
+                }
+                word = word c; i++
+            }
+            continue
+        }
+        if (c == "$" && substr(s, i + 1, 1) == "(") { inword = 1; i = cmdsub(s, i + 2, n); word = word "x"; continue }
+        if (c == "`") {
+            inword = 1
+            j = index(substr(s, i + 1), "`")
+            if (j == 0) { i = n + 1; continue }
+            enqueue(substr(s, i + 1, j - 1)); i += j + 1; word = word "x"; continue
+        }
+        if (c == "#" && !inword) {
+            j = index(substr(s, i), "\n")
+            if (j == 0) { i = n + 1 } else { i += j - 1 }
+            continue
+        }
+        if (c == " " || c == "\t" || c == "\r") { flush_word(); i++; continue }
+        if (c == "\n") {
+            end_cmd(); i++
+            if (nheredoc > 0) i = read_heredocs(s, i, n)
+            continue
+        }
+        if (c == ";" || c == "&" || c == "|" || c == "(" || c == ")") { end_cmd(); i++; continue }
+        if (substr(s, i, 2) == "<<" && substr(s, i, 3) != "<<<") {
+            flush_word(); i += 2; dash = 0
+            if (substr(s, i, 1) == "-") { dash = 1; i++ }
+            while (substr(s, i, 1) == " " || substr(s, i, 1) == "\t") i++
+            delim = ""
+            while (i <= n) {
+                c = substr(s, i, 1)
+                if (c ~ /[ \t\n;&|()<>]/) break
+                if (c != "\047" && c != "\"" && c != "\\") delim = delim c
+                i++
+            }
+            nheredoc++; HD[nheredoc] = delim; HDDASH[nheredoc] = dash
+            continue
+        }
+        word = word c; inword = 1; i++
+    }
+    end_cmd()
+}
+
+# ── option parsing shared by the CLIs: positionals P/PI, output format, -f/--format value, --raw ──
+function kparse(A, s, n, shortvals,    i, w, eq, key, val, f, rest) {
+    split("", P); split("", PI)
+    np = 0; outfmt = ""; fmtval = ""; dd = 0; raw = 0
+    for (i = s; i <= n; i++) {
+        w = A[i]
+        if (w == "--") { dd = i; break }
+        if (substr(w, 1, 2) == "--") {
+            eq = index(w, "="); key = w; val = ""
+            if (eq) { key = substr(w, 1, eq - 1); val = substr(w, eq + 1) }
+            if (key == "--output") { if (!eq) { i++; val = A[i] } outfmt = tolower(val) }
+            else if (key == "--format") { if (!eq) { i++; val = A[i] } fmtval = val }
+            else if (key == "--raw") raw = 1
+            else if (!eq && (key in LV)) i++
+            continue
+        }
+        if (substr(w, 1, 1) == "-" && length(w) > 1) {
+            f = substr(w, 2, 1); rest = substr(w, 3)
+            if (f == "o") {
+                if (rest == "") { i++; val = A[i] } else val = (substr(rest, 1, 1) == "=" ? substr(rest, 2) : rest)
+                outfmt = tolower(val)
+            } else if (f == "f" && index(shortvals, "f")) {
+                if (rest == "") { i++; val = A[i] } else val = (substr(rest, 1, 1) == "=" ? substr(rest, 2) : rest)
+                fmtval = val
+            } else if (rest == "" && f != "" && index(shortvals, f)) i++
+            continue
+        }
+        np++; P[np] = w; PI[np] = i
+    }
+}
+function skipopts(A, s, n, vals) {
+    while (s <= n && substr(A[s], 1, 1) == "-") {
+        if (length(A[s]) == 2 && index(vals, substr(A[s], 2, 1))) s += 2
+        else s++
+    }
+    return s
+}
+function is_assign(w) { return w ~ /^[A-Za-z_][A-Za-z0-9_]*=/ }
+
+# ── file classification for the reader commands ──
+function code_file(b) { return b ~ /\.(cs|ts|tsx|js|jsx|mjs|cjs|go|py|java|kt|rs|md)$/ }
+# A design-token file is not a credential: a stylesheet, or a file under a design, theme or style directory, is
+# fine unless it sits in a secrets or credentials directory. A bare token.json (an OAuth refresh-token file) is not.
+function token_ok(l, b) {
+    if (l ~ /(^|\/)(secrets?|credentials?)\//) return 0
+    if (b ~ /\.(css|scss|less)$/) return 1
+    return l ~ /(^|\/)(design|design-tokens|themes?|styles?)\//
+}
+function sensitive_path(w,    l, b) {
+    l = tolower(w); b = l; sub(/.*\//, "", b)
+    if (l ~ /(^|\/)\.kube\// || b == "kubeconfig" || b ~ /\.kubeconfig$/) return "a kubeconfig"
+    if (b ~ /^\.env/ || b ~ /\.env$/) { if (b ~ /\.(example|sample|template|dist|defaults?)$/) return ""; return "an .env file" }
+    if (b ~ /\.(pem|p12|pfx)$/) return "a key or certificate file"
+    if (b == "id_rsa" || b == "id_ed25519" || b == "id_ecdsa" || b == "id_dsa") return "a private key"
+    if (b ~ /(^|[._-])tokens?($|[._-])/ && !code_file(b) && !token_ok(l, b)) return "a token file"
+    if (b == ".netrc" || b == ".npmrc" || b == ".pgpass" || b == ".git-credentials") return "a credentials file"
+    if (b == "credentials" && l ~ /\.aws\//) return "the AWS credentials file"
+    if (l ~ /\.docker\/config\.json$/) return "the Docker registry credentials"
+    if (l ~ /\/proc\/[^\/]*\/environ$/) return "a process environment"
+    if (l ~ /^\/(var\/)?run\/secrets\//) return "mounted secrets"
+    return ""
+}
+
+# ── tools ──
+function kube(A, s, n,    verb, m, parts, k, r, rlist) {
+    kparse(A, s + 1, n, "nlcsfkLR")
+    verb = P[1]
+    if (verb == "exec") {
+        if (dd) analyze(A, dd + 1, n)
+        else if (np >= 3) analyze(A, PI[3], n)
+        return
+    }
+    if (verb == "config") {
+        if (P[2] == "view" && raw) report("kubectl config view --raw prints the cluster credentials", "kubectl config view (redacted), kubectl config current-context, or kubectl config get-contexts")
+        return
+    }
+    if (verb != "get" && verb != "describe") return
+    # `get pods,cm` and `get pod web` name one resource type; `get svc/web secret/db` names one per argument.
+    rlist = P[2]
+    if (index(P[2], "/")) for (k = 3; k <= np; k++) if (index(P[k], "/")) rlist = rlist "," P[k]
+    m = split(tolower(rlist), parts, ",")
+    for (k = 1; k <= m; k++) {
+        r = parts[k]; sub(/\/.*/, "", r); sub(/\..*/, "", r)
+        if (r == "secret" || r == "secrets") {
+            if (verb == "describe" || outfmt != "name")
+                report("kubectl " verb " secret prints secret data", "kubectl get secrets -o name to list them, or name the secret and key in your report instead of reading it")
+        } else if (r in SENS) {
+            if (verb == "describe")
+                report("kubectl describe " r " prints the full container spec, including inline credentials", "kubectl get " r " -o jsonpath=" SQ "{.items[*].spec.containers[*].image}" SQ ", -o custom-columns=NAME:.metadata.name,STATUS:.status.phase, -o name, or kubectl get events / kubectl logs; say which field you need")
+            else if (outfmt == "json" || outfmt == "yaml")
+                report("kubectl get " r " -o " outfmt " prints the full container spec, including inline credentials", "-o jsonpath=" SQ "{.items[*].spec.containers[*].image}" SQ ", -o custom-columns=NAME:.metadata.name,STATUS:.status.phase, -o name, -o wide, or the status fields you need")
+        }
+    }
+}
+function fmt_leaks(f) {
+    f = tolower(f)
+    return f ~ /env|json|\.args/ || f ~ /[{][{] *\.? *[}][}]/ || f ~ /\.config *[}][}]/
+}
+function dock(A, s, n,    off, sub1, nxt, insp, k, listing) {
+    kparse(A, s + 1, n, "Hceuwlpfv")
+    off = (P[1] == "compose") ? 1 : 0
+    sub1 = P[1 + off]; nxt = P[2 + off]
+    insp = (sub1 == "inspect") || ((sub1 == "container" || sub1 == "image" || sub1 == "service") && nxt == "inspect")
+    if (insp && (fmtval == "" || fmt_leaks(fmtval)))
+        report("docker inspect prints the container environment, including credentials", "docker inspect --format " SQ "{{.State.Status}}" SQ " (or {{.Config.Image}}, {{.NetworkSettings.IPAddress}}), docker ps, or docker logs")
+    if (off && sub1 == "config") {
+        for (k = s + 1; k <= n; k++) if (A[k] ~ /^(--services|--volumes|--profiles|--images|--networks|--quiet|-q)$/) listing = 1
+        if (!listing) report("docker compose config prints the resolved environment, including credentials", "docker compose config --services, or read the compose file and name the variables instead of printing their values")
+    }
+    if (sub1 == "exec" && np >= 3 + off) analyze(A, PI[3 + off], n)
+}
+function gh(A, s, n,    i, w, mutating, k) {
+    kparse(A, s + 1, n, "XHfFqtR")
+    if (P[1] == "secret") {
+        if (P[2] != "set" && P[2] != "delete" && P[2] != "remove")
+            report("gh secret " P[2] " reads the repository secret store", "gh secret set NAME (writes nothing to the output); refer to secrets by name only")
+        return
+    }
+    if (P[1] == "auth") {
+        if (P[2] == "token") report("gh auth token prints the GitHub token", "gh auth status (without --show-token) to confirm you are signed in")
+        else if (P[2] == "status")
+            for (i = s + 1; i <= n; i++) if (A[i] == "-t" || A[i] == "--show-token") report("gh auth status --show-token prints the GitHub token", "gh auth status without --show-token")
+        return
+    }
+    if (P[1] == "api") {
+        mutating = 0
+        for (i = s + 1; i < n; i++) if (A[i] == "-X" || A[i] == "--method") { w = toupper(A[i + 1]); if (w == "PUT" || w == "PATCH" || w == "DELETE") mutating = 1 }
+        if (!mutating)
+            for (k = 2; k <= np; k++)
+                if (tolower(P[k]) ~ /(^|\/)secrets([\/?]|$)/) report("gh api " P[k] " reads the repository secret store", "gh secret set NAME for writes; name the secret instead of reading it")
+    }
+}
+function vault(A, s, n) {
+    kparse(A, s + 1, n, "")
+    if (P[1] == "read" || (P[1] == "kv" && (P[2] == "get" || P[2] == "read")))
+        report("vault " P[1] (P[1] == "kv" ? " " P[2] : "") " prints secret values", "vault kv list or vault kv metadata get for the key names; name the path and key in your report")
+}
+function aws(A, s, n,    i, decrypt) {
+    kparse(A, s + 1, n, "")
+    if (P[1] == "secretsmanager" && P[2] == "get-secret-value") report("aws secretsmanager get-secret-value prints the secret", "aws secretsmanager list-secrets or describe-secret (metadata only)")
+    if (P[1] == "configure" && P[2] == "export-credentials") report("aws configure export-credentials prints the credentials", "aws sts get-caller-identity to confirm who you are")
+    if (P[1] == "ssm" && P[2] ~ /^get-parameter/) {
+        decrypt = 0
+        for (i = s + 1; i <= n; i++) if (A[i] == "--with-decryption") decrypt = 1
+        if (decrypt) report("aws ssm " P[2] " --with-decryption prints decrypted parameters", "aws ssm describe-parameters, or get-parameter without --with-decryption")
+    }
+}
+function azure(A, s, n) {
+    kparse(A, s + 1, n, "n")
+    if (P[1] == "keyvault" && P[2] == "secret" && (P[3] == "show" || P[3] == "download")) report("az keyvault secret " P[3] " prints the secret", "az keyvault secret list, or az keyvault secret show-deleted metadata only; name the secret in your report")
+    if (P[1] == "account" && P[2] == "get-access-token") report("az account get-access-token prints a bearer token", "az account show")
+}
+function gcloud(A, s, n,    k) {
+    kparse(A, s + 1, n, "")
+    if (P[1] == "secrets" && P[2] == "versions" && P[3] == "access") report("gcloud secrets versions access prints the secret", "gcloud secrets versions list, or gcloud secrets describe (metadata only)")
+    if (P[1] == "auth") for (k = 2; k <= np; k++) if (P[k] ~ /^print-(access|identity)-token$/) report("gcloud auth " P[k] " prints a token", "gcloud auth list")
+}
+function reader(A, s, n,    b, k, w, mode, havepat, need, afterdd, kind, valued, valued2) {
+    b = base(A[s]); mode = ""; valued = " "; valued2 = " "
+    if (b ~ /^(grep|egrep|fgrep|rg|ag)$/) { mode = "pattern"; valued = " -m -A -B -C -g -t -T -d -D --glob --type --type-not --max-count --include --exclude --exclude-dir --context --after-context --before-context --max-depth --threads " }
+    else if (b ~ /^(sed|awk|gawk|jq|yq)$/) { mode = "script"; valued = " -v -F --indent "; valued2 = " --arg --argjson --slurpfile --rawfile " }
+    # The first operand is the pattern or script unless -e/-f/--regexp/--file/--expression supplies it; only the rest are files.
+    havepat = 0
+    if (mode != "") for (k = s + 1; k <= n; k++) if (A[k] ~ /^-[a-zA-Z]*[ef]$/ || A[k] ~ /^--(regexp|file|expression|from-file)(=|$)/) havepat = 1
+    need = (mode != "" && !havepat); afterdd = 0
+    for (k = s + 1; k <= n; k++) {
+        w = A[k]
+        if (w == "--" && !afterdd) { afterdd = 1; continue }
+        if (!afterdd && substr(w, 1, 1) == "-" && length(w) > 1) {
+            if (mode != "" && (w ~ /^-[a-zA-Z]*[ef]$/ || w ~ /^--(regexp|file|expression|from-file)$/ || index(valued, " " w " "))) k++
+            else if (index(valued2, " " w " ")) k += 2
+            continue
+        }
+        if (need) { need = 0; continue }
+        kind = sensitive_path(w)
+        if (kind != "") report(b " of " kind " prints credentials", "name the file and the key you need in your report; ask the user to confirm a value instead of printing it; for an env template read the .env.example")
+    }
+}
+
+function analyze(A, s, n,    w, b, k, names, p) {
+    while (s <= n) {
+        w = A[s]; b = base(w)
+        if (is_assign(w)) { s++; continue }
+        if (w ~ /^[0-9]*[<>]/) { s += (w ~ /^[0-9]*[<>]+&?-?$/) ? 2 : 1; continue }
+        if (b in KW) { s++; continue }
+        if (b == "command" || b == "builtin") { s++; if (s <= n && (A[s] == "-v" || A[s] == "-V")) return; continue }
+        if (b == "sudo" || b == "doas") { s = skipopts(A, s + 1, n, "ugChprtUD"); continue }
+        if (b == "xargs") { s = skipopts(A, s + 1, n, "IniPLdsEa"); continue }
+        if (b == "timeout") { s = skipopts(A, s + 1, n, "ks") + 1; continue }
+        if (b == "nice" || b == "watch") { s = skipopts(A, s + 1, n, "n"); continue }
+        if (b == "nohup" || b == "time" || b == "exec" || b == "setsid") { s = skipopts(A, s + 1, n, ""); continue }
+        if (b == "rtk") { s++; if (s <= n && base(A[s]) == "proxy") s++; continue }
+        if (b == "env") {
+            s++
+            while (s <= n) {
+                w = A[s]
+                if (is_assign(w)) s++
+                else if (w == "-u" || w == "-C" || w == "-S" || w == "--unset" || w == "--chdir" || w == "--split-string") s += 2
+                else if (substr(w, 1, 1) == "-") s++
+                else break
+            }
+            if (s > n) { report("env with no command prints the whole environment, including credentials (env | ... is blocked too)", "printenv NAME for one variable that is not a credential, or [ -n \"${NAME:-}\" ] && echo set to test that a variable exists"); return }
+            continue
+        }
+        break
+    }
+    if (s > n) return
+    b = base(A[s])
+    if (b == "bash" || b == "sh" || b == "zsh" || b == "dash" || b == "ksh") {
+        for (k = s + 1; k <= n; k++)
+            if (A[k] ~ /^-[a-zA-Z]*c[a-zA-Z]*$/) { enqueue(A[k + 1]); return }
+        if (nheredoc > 0) hd_shell = 1
+        return
+    }
+    if (b == "eval") { p = ""; for (k = s + 1; k <= n; k++) p = p " " A[k]; enqueue(p); return }
+    if (b == "kubectl" || b == "oc") return kube(A, s, n)
+    if (b == "docker" || b == "podman") return dock(A, s, n)
+    if (b == "docker-compose") { split("", T); T[1] = "docker"; T[2] = "compose"; for (k = s + 1; k <= n; k++) T[k - s + 2] = A[k]; return dock(T, 1, n - s + 2) }
+    if (b == "gh") return gh(A, s, n)
+    if (b == "vault") return vault(A, s, n)
+    if (b == "aws") return aws(A, s, n)
+    if (b == "az") return azure(A, s, n)
+    if (b == "gcloud") return gcloud(A, s, n)
+    if (b == "pulumi") {
+        for (k = s + 1; k <= n; k++) if (A[k] ~ /^--show-secrets/) report("pulumi --show-secrets prints decrypted secrets", "pulumi config / pulumi stack output without --show-secrets (secrets stay masked)")
+        return
+    }
+    if (b == "printenv") {
+        names = 0
+        for (k = s + 1; k <= n; k++) {
+            if (substr(A[k], 1, 1) == "-") continue
+            names++
+            if (tolower(A[k]) ~ /token|secret|key|pass|pwd|credential|auth|cert|conn|dsn/) report("printenv " A[k] " prints a credential", "[ -n \"${" A[k] ":-}\" ] && echo set, which confirms it exists without printing it")
+        }
+        if (names == 0) report("printenv with no variable name prints the whole environment, including credentials", "printenv with the one non-credential variable you need, e.g. printenv HOME")
+        return
+    }
+    if (b == "export") {
+        names = 0; p = 0
+        for (k = s + 1; k <= n; k++) { if (A[k] == "-p") p = 1; else if (substr(A[k], 1, 1) != "-") names++ }
+        if (p || names == 0) report("export with no variable name prints the whole environment, including credentials", "printenv with the one non-credential variable you need")
+        return
+    }
+    if (b == "declare" || b == "typeset") {
+        names = 0; p = 0
+        for (k = s + 1; k <= n; k++) { if (A[k] ~ /^-[a-zA-Z]*[px][a-zA-Z]*$/) p = 1; else if (substr(A[k], 1, 1) != "-") names++ }
+        if (p && names == 0) report(b " -p/-x with no variable name prints the whole environment, including credentials", "printenv with the one non-credential variable you need")
+        return
+    }
+    if (b ~ /^(cat|tac|nl|less|more|head|tail|bat|batcat|strings|xxd|od|hexdump|cut|sort|uniq|base64|grep|egrep|fgrep|rg|ag|sed|awk|gawk|jq|yq)$/) reader(A, s, n)
+}
+
+BEGIN {
+    SQ = "\047"
+    split("namespace context kubeconfig server cluster user as as-group selector field-selector container label-columns sort-by request-timeout filename kustomize template chunk-size token env env-file workdir host config project-name file profile detach-keys log-level method header field raw-field jq repo hostname input region query endpoint-url vault-name subscription resource-group name id version project secret account", L, " ")
+    for (i in L) LV["--" L[i]] = 1
+    split("! { } if then else elif do while until", L, " ")
+    for (i in L) KW[L[i]] = 1
+    split("pods po pod deployments deployment deploy statefulsets statefulset sts daemonsets daemonset ds jobs job cronjobs cronjob cj configmaps configmap cm replicasets replicaset rs replicationcontrollers rc all", L, " ")
+    for (i in L) SENS[L[i]] = 1
+    enqueue(ENVIRON["GS_COMMAND"])
+    while (qi < queued) { qi++; tokenize(queue[qi]) }
+}
+AWK
+
+findings="$(GS_COMMAND="$command_text" LC_ALL=C awk "$awk_program" </dev/null)"
+[ -n "$findings" ] || exit 0
+
+{
+    while IFS=$'\t' read -r what alternative; do
+        [ -n "$what" ] || continue
+        printf 'BLOCKED by cratis-guard-secrets: %s. Use instead: %s.\n' "$what" "$alternative"
+    done <<EOF
+$findings
+EOF
+    cat <<'EOF'
+
+secrets.md: a credential must never enter an agent transcript, and a transcript is saved, summarized and
+shared. Ask for the field you need (a jsonpath, custom-columns, -o name, a status field) and say which one;
+refer to a secret by name (secret/key, environment variable) in notes, briefs and messages, never by value.
+
+If a value has already appeared in output: stop, do not copy it onward, report "SECURITY INCIDENT" with the
+tool-call location and the credential kind, and ask for rotation.
+
+Do not retry this, rephrase it, or work around the guard (another wrapper, a script file, a variable, an
+alias). A person who authorized the read sets CRATIS_HOOKS_ALLOW_SECRET_READS=1 in the environment the agent
+harness was started from; setting it inside the command has no effect.
+EOF
+} >&2
+exit 2

package/package/corpus/hooks/settings.template.json

@@ -18,6 +18,10 @@
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR\"/.cratis/ai/hooks/scripts/cratis-guard-store-mutations.sh"
           },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.cratis/ai/hooks/scripts/cratis-guard-secrets.sh"
+          },
           {
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR\"/.cratis/ai/hooks/scripts/cratis-guard-pr-body.sh"

package/package/corpus/rules/browser.md

@@ -0,0 +1,45 @@
+---
+applyTo: "**/*"
+---
+
+# Browser use
+
+Browser access is a capability, not authority (see
+[`capability-is-not-authority.md`](./capability-is-not-authority.md)). Every line is tagged
+**[contract]** (binding) or **[convention]** (the house default) per the Three Levels of
+Authority in [`general.md`](./general.md). Read this before any browser call.
+
+## Permit and handoff
+
+- **[contract] Production is read-only.** Write to a production site only when the user's
+  request or an applicable policy names that exact action. A configured browser tool is not
+  a permit.
+- **[contract] One production tab per session.** No parallel polling or parallel findings on
+  production. Run the health check first, close idle browsers, and look for stale tabs from
+  other sessions before opening one.
+- **[convention] Prefer staging or a local copy** for interactive and visual smoke runs.
+- **[contract] Only the `browser-operator` agent receives browser tools.** Hand it the URL,
+  scope, permit and artifact directory. The main session does not do browser work itself
+  unless no such agent is available. No other agent gets browser tools.
+- **[contract] Stop for a human on sign-in, 2FA or CAPTCHA.** Record
+  `UI UNVERIFIED — needs human sign-in` and continue the other lanes. Do not block on it.
+
+## Artifacts and uploads
+
+- **[contract] Write artifacts and stage uploads only under `.ai-work/<task>/browser/`**
+  (see [`local-work-artifacts.md`](./local-work-artifacts.md)). If a path guard blocks you,
+  stop and report. Never monkey-patch DOM or file APIs to get around it.
+- **[contract] No secrets or tokens in artifacts, URLs or logs.**
+
+## Evidence
+
+- **[contract] A UI verification records:** URL, build or version, screenshot path under
+  `.ai-work/`, correlation id, timestamp and environment. Without these it is unverified.
+
+## Headless production-smoke checklist
+
+- **[convention]** Port-forward to the service.
+- **[convention]** Front it with a GET-only proxy that injects the required headers.
+- **[convention]** Drive it from a fresh headless browser with no persistent profile.
+- **[convention]** Give any signed-in profile a single owner.
+- **[convention]** Tear down the browser, proxy and port-forward when done.

package/package/corpus/rules/general.md

@@ -146,7 +146,9 @@ A claim is only as good as the signal behind it — a build result, a test run,
 | MongoDB queries — native driver API over LINQ; paging and sorting belong to Arc | `mongodb.md` |
 | Before writing a commit message, committing, pushing or opening/editing a PR: read both | `git-commits.md`, `pull-requests.md` |
 | Reading, citing and superseding a decision record | the **cratis-engineering-decision-record** skill |
+| Before any browser call: production permit, handoff, artifact paths, evidence | `browser.md` |
 | Whether you are allowed to do the thing you are able to do | `capability-is-not-authority.md` |
+| Before running a command that could print a credential, or when a secret value appears in output | `secrets.md` |
 | What must stop and ask a human | `capability-is-not-authority.md` (absent authority for a consequential effect: stop and ask) |
 | What counts as evidence that something works | `verification-discipline.md` |
 | Before writing a session note, plan or handover: where they may live (`.ai-work/` only) | `local-work-artifacts.md` |

package/package/corpus/rules/local-work-artifacts.md

@@ -53,6 +53,9 @@ dumps, and similar coordination files. These are **work records, not documentati
   worktree and branch behind, which is why the script exists. If the branch must outlive the
   task unmerged, leave the worktree and say so in the handoff. Never `--force` a removal; a
   refusal means look, not push harder.
+- **Scan for secrets before archiving or sharing.** Before anything from `.ai-work/` is archived,
+  attached or shared, run `gitleaks detect --no-git --source <dir>` (or the repository's equivalent)
+  and redact every finding. See [`secrets.md`](./secrets.md).
 - **A decision log is not a work record.** A decision — a durable choice with a
   decider and a date — is documentation: it lives in **`decisions/`** (or the
   repository's documented decisions folder, such as `.cratis/ai.json` `process.decisions.path`) and is reviewed like any other

package/package/corpus/rules/review-reports.md

@@ -65,3 +65,14 @@ scope limits when combining reports.
 When a workflow requires a typed review envelope, preserve its schema and express
 these sections, verdict meanings, and scope limits through its existing fields.
 Do not append a competing Markdown report or invent envelope fields.
+
+## Reviewer independence
+
+- **[contract]** Run a reviewer on a different provider family than the author's model
+  where the harness can select one. The reviewer agents declare
+  `reviewIndependence: different-provider` and the `reviewer` model tier.
+- **[contract]** Where the harness cannot select a provider, state `single-provider` in the
+  report header and on the Not examined line.
+- **[contract]** A provider or tool error makes the review **Incomplete**. Fall back once
+  to the other family. Never report a failed verdict, or Approved, because the reviewer
+  could not run.

package/package/corpus/rules/secrets.md

@@ -0,0 +1,34 @@
+---
+applyTo: "**/*"
+---
+
+# Secrets never enter agent transcripts
+
+A transcript is saved, summarized and shared, so a credential that is printed once is leaked.
+Every line is tagged **[contract]** (binding) per the Three Levels of Authority in
+[`general.md`](./general.md). The `cratis-guard-secrets` hook blocks the commands below
+(see [`.cratis/ai/hooks/README.md`](../hooks/README.md)); the rule holds where no hook runs.
+
+## Commands
+
+- **[contract] Never run a command whose output contains credentials:** `kubectl get … -o json|yaml`
+  or `kubectl describe` on pods, deployments, statefulsets, daemonsets, jobs, configmaps or
+  secrets; `kubectl get secret`; `kubectl config view --raw`; `env`, `printenv`, `export -p`
+  (including `env | …`); `docker inspect`; `gh secret`, `gh api …/secrets`, `gh auth token`;
+  `vault read`, `vault kv get`; cloud secret-manager reads; `pulumi … --show-secrets`;
+  reading kubeconfigs, `.env*` files, private keys or token files.
+- **[contract] Project the field you need and say which one:** `-o jsonpath='{.spec.containers[*].image}'`,
+  `-o custom-columns=…`, `kubectl get … -o name`, status fields, `kubectl logs`, `docker inspect --format`.
+  Read a `.env.example`, never the `.env`.
+
+## Values
+
+- **[contract] Never paste, echo or log a credential**, and never put one in a brief, handoff,
+  issue, PR, message or commit. Reference a secret by name only (secret/key, environment variable).
+- **[contract] When a value appears in output, stop.** Do not copy it onward. Report
+  **SECURITY INCIDENT** with the file or tool-call location and the credential kind, and ask for
+  rotation. Do not retry the command in another form.
+- **[contract] Redact before archiving.** Scan and redact a work record before it is archived or
+  shared (see [`local-work-artifacts.md`](./local-work-artifacts.md)).
+- **[contract] The escape hatch is a human's.** `CRATIS_HOOKS_ALLOW_SECRET_READS=1` is set by the
+  person who authorized the read, in the harness environment, never by an agent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.100.0",
+  "version": "7.101.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [