claude-code-kit 0.40.0__tar.gz → 0.41.0__tar.gz

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "claude-kit",
       "source": "./",
       "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker): install CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json, then run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.",
-      "version": "0.40.0",
+      "version": "0.41.0",
       "license": "MIT",
       "keywords": ["sdlc", "agents", "orchestration", "quality-gates", "workflow", "scaffold", "cookiecutter"]
     }

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-kit",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker). `claude-kit init` asks ordered questions and installs CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates with working memory and a self-improving learnings loop.",
   "author": {
     "name": "Arjunsingh Yadav",

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to claude-kit are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project uses
 [semantic versioning](https://semver.org/).
 
+## [0.41.0] — 2026-06-26
+
+**Escalation discipline + safety/shell review lenses** (PR 3 of 4 from the MIT
+`athola/claude-night-market` audit; re-derived stack-agnostic).
+
+- **`rules/model-tiers.md`** gains a **"When to escalate a tier"** section: the Iron Law
+  (no escalation without investigation first), a 4-question gate (understood? investigated? right lever?
+  worth it?), legitimate triggers, and an **anti-rationalization table** that catches "maybe a smarter
+  model will figure it out." Ties into the agent-resilience 3-strike rule + quality-gates escalation.
+- **`rules/human-in-the-loop.md`** gains a **reversibility gate**: classify a decision as one-way vs
+  two-way door across undo-cost/blast-radius/data/externalization/commitment, and scale review
+  proportionally (proceed → adversarial pass → stop-and-ask + premortem/watch-points/reversal-plan).
+  Also flags *false irreversibility*. (Adapted from war-room's reversibility scoring; the multi-LLM
+  panel was dropped — it overlaps the orchestrator/`devils-advocate`.)
+- **`skills/safety-critical-patterns/`** (new core skill) — NASA Power-of-10 high-reliability lens
+  adapted language-neutral, **gated by "match rigor to consequence"** (full for money/medical/
+  data-integrity/auth/irreversible; light for scripts) so it never over-applies to CRUD. Composes with
+  `risk-classification`.
+- **`skills/shell-review/`** (new core skill) — audits CI/hook/build/wrapper shell for exit-code
+  propagation (`set -euo pipefail`, capture-output-and-status), POSIX-vs-bash portability, safety
+  (quote/brace vars, `:?` required vars, `cd` in a subshell, `mktemp`+`trap`), and library/executable
+  structure; `shellcheck` as the backstop. (Re-derived without the upstream's bespoke logging/guard
+  conventions.)
+- Counts: **99 → 101** total skills (**53 → 55** core; collection unchanged at 46).
+
 ## [0.40.0] — 2026-06-26
 
 **Review grounding + addition scrutiny** (PR 2 of 4 from the MIT `athola/claude-night-market` audit;

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-kit
-Version: 0.40.0
+Version: 0.41.0
 Summary: Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.
 Project-URL: Homepage, https://github.com/ajyadav013/claude-kit
 Project-URL: Repository, https://github.com/ajyadav013/claude-kit
@@ -84,7 +84,7 @@ Quick start) for the full breakdown of any row.
 | 🔁 **Pipeline & quality gates** | Gate-enforced progression (zero open Critical/High/Medium to advance), per-profile gate sets, a fast-track for small changes, and an anti-sycophancy `devils-advocate` pass |
 | 🤖 **Agent roster** | **28** tiered agents + per-database overlays + **6** org personas, led by an Orchestrator that never writes code |
 | 🔍 **Self-verification & review** | RARV green-Verify (real commands, not imagined), blind parallel review, and read-only risk classification |
-| 📐 **Rules & skills** | **23** stack-agnostic core rules (incl. 8 agent-operation rules) + **99** context-activated skills (53 core + 46 stack-collection) |
+| 📐 **Rules & skills** | **23** stack-agnostic core rules (incl. 8 agent-operation rules) + **101** context-activated skills (55 core + 46 stack-collection) |
 | 🧱 **Stacks & overlays** | Stack-agnostic core + **10** overlay rule sets (React · FastAPI · Go · Postgres · Mongo) wired to your exact commands, incl. a full React design system |
 | 🎚️ **Profiles, scopes & org** | **3** rigor profiles · **3** scopes · **5** autonomy levels · **7** org packs + **10** policy rules |
 | 🧠 **Memory & learning** | Working memory across context compaction + a cost-aware learnings loop (`capture_mode`) so the same mistake isn't repeated |
@@ -281,7 +281,7 @@ need.
 - **23 stack-agnostic core rules** in [`rules/`](rules/) — `mandatory-workflow`, `quality-gates`,
   `rarv-cycle`, `continuity`, plus eight agent-operation rules and `autonomy-levels` +
   `risk-classification` (see [`docs/agentic-patterns.md`](docs/agentic-patterns.md)).
-- **99 on-demand skills** in [`skills/`](skills/) (53 core + 46 stack-collection) — spec-driven dev, planning, TDD, debugging, code
+- **101 on-demand skills** in [`skills/`](skills/) (55 core + 46 stack-collection) — spec-driven dev, planning, TDD, debugging, code
   review, threat modeling, and more — activated by context and led by the `sdlc` entrypoint.
 - **Profile-subset install** — each profile installs a strict subset of agents, skills, hooks, and
   rules (`lean ⊂ standard ⊂ enterprise`), from fast track to full audit.
@@ -437,7 +437,7 @@ owned gates, and the rule that **no gate passes on an unproven verdict**.
 | **[wshobson/agents](https://github.com/wshobson/agents)** & similar agent collections | Large libraries of individual subagent prompts you pick from | A **smaller, opinionated set wired into a sequenced pipeline with owned quality gates** — agents aren't a menu, they're stages that hand off and block on each other. Adopt-by-reuse, not by accumulation. |
 | **[GitHub spec-kit](https://github.com/github/spec-kit)** | A spec-driven workflow (constitution → spec → tasks → analyze) | The same coverage-gate idea (the `story-planner` 1f gate + `task-tracker-sync`) **absorbed into a broader** lifecycle that also covers review, security, build, test, release, and observability gates. Complementary, wider scope. |
 | **claude-flow / multi-agent runtimes** | Runtime orchestrators that *execute* swarms of agents | **Portable configuration**, not a running process — the orchestration is described in rules the host (Claude Code) executes. No daemon, no lock-in, no app code. |
-| **dotfiles / `CLAUDE.md` starters** | A single rules file or settings snippet | A **catalog-driven generator**: resolves your stack/profile/scope into the right subset of 23 rules, 28 agents, 99 skills, gates, and hooks, kept **upgradeable** (`claude-kit upgrade` preserves your edits via owner + checksum). |
+| **dotfiles / `CLAUDE.md` starters** | A single rules file or settings snippet | A **catalog-driven generator**: resolves your stack/profile/scope into the right subset of 23 rules, 28 agents, 101 skills, gates, and hooks, kept **upgradeable** (`claude-kit upgrade` preserves your edits via owner + checksum). |
 
 **Choose claude-kit when** you want a consistent, reviewable, **gate-enforced** autonomous-SDLC setup
 that's the same across every repo and stack, installs in seconds, ships nothing you have to run, and

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/README.md

@@ -54,7 +54,7 @@ Quick start) for the full breakdown of any row.
 | 🔁 **Pipeline & quality gates** | Gate-enforced progression (zero open Critical/High/Medium to advance), per-profile gate sets, a fast-track for small changes, and an anti-sycophancy `devils-advocate` pass |
 | 🤖 **Agent roster** | **28** tiered agents + per-database overlays + **6** org personas, led by an Orchestrator that never writes code |
 | 🔍 **Self-verification & review** | RARV green-Verify (real commands, not imagined), blind parallel review, and read-only risk classification |
-| 📐 **Rules & skills** | **23** stack-agnostic core rules (incl. 8 agent-operation rules) + **99** context-activated skills (53 core + 46 stack-collection) |
+| 📐 **Rules & skills** | **23** stack-agnostic core rules (incl. 8 agent-operation rules) + **101** context-activated skills (55 core + 46 stack-collection) |
 | 🧱 **Stacks & overlays** | Stack-agnostic core + **10** overlay rule sets (React · FastAPI · Go · Postgres · Mongo) wired to your exact commands, incl. a full React design system |
 | 🎚️ **Profiles, scopes & org** | **3** rigor profiles · **3** scopes · **5** autonomy levels · **7** org packs + **10** policy rules |
 | 🧠 **Memory & learning** | Working memory across context compaction + a cost-aware learnings loop (`capture_mode`) so the same mistake isn't repeated |
@@ -251,7 +251,7 @@ need.
 - **23 stack-agnostic core rules** in [`rules/`](rules/) — `mandatory-workflow`, `quality-gates`,
   `rarv-cycle`, `continuity`, plus eight agent-operation rules and `autonomy-levels` +
   `risk-classification` (see [`docs/agentic-patterns.md`](docs/agentic-patterns.md)).
-- **99 on-demand skills** in [`skills/`](skills/) (53 core + 46 stack-collection) — spec-driven dev, planning, TDD, debugging, code
+- **101 on-demand skills** in [`skills/`](skills/) (55 core + 46 stack-collection) — spec-driven dev, planning, TDD, debugging, code
   review, threat modeling, and more — activated by context and led by the `sdlc` entrypoint.
 - **Profile-subset install** — each profile installs a strict subset of agents, skills, hooks, and
   rules (`lean ⊂ standard ⊂ enterprise`), from fast track to full audit.
@@ -407,7 +407,7 @@ owned gates, and the rule that **no gate passes on an unproven verdict**.
 | **[wshobson/agents](https://github.com/wshobson/agents)** & similar agent collections | Large libraries of individual subagent prompts you pick from | A **smaller, opinionated set wired into a sequenced pipeline with owned quality gates** — agents aren't a menu, they're stages that hand off and block on each other. Adopt-by-reuse, not by accumulation. |
 | **[GitHub spec-kit](https://github.com/github/spec-kit)** | A spec-driven workflow (constitution → spec → tasks → analyze) | The same coverage-gate idea (the `story-planner` 1f gate + `task-tracker-sync`) **absorbed into a broader** lifecycle that also covers review, security, build, test, release, and observability gates. Complementary, wider scope. |
 | **claude-flow / multi-agent runtimes** | Runtime orchestrators that *execute* swarms of agents | **Portable configuration**, not a running process — the orchestration is described in rules the host (Claude Code) executes. No daemon, no lock-in, no app code. |
-| **dotfiles / `CLAUDE.md` starters** | A single rules file or settings snippet | A **catalog-driven generator**: resolves your stack/profile/scope into the right subset of 23 rules, 28 agents, 99 skills, gates, and hooks, kept **upgradeable** (`claude-kit upgrade` preserves your edits via owner + checksum). |
+| **dotfiles / `CLAUDE.md` starters** | A single rules file or settings snippet | A **catalog-driven generator**: resolves your stack/profile/scope into the right subset of 23 rules, 28 agents, 101 skills, gates, and hooks, kept **upgradeable** (`claude-kit upgrade` preserves your edits via owner + checksum). |
 
 **Choose claude-kit when** you want a consistent, reviewable, **gate-enforced** autonomous-SDLC setup
 that's the same across every repo and stack, installs in seconds, ships nothing you have to run, and

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-code-kit"
-version = "0.40.0"
+version = "0.41.0"
 description = "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop."
 readme = "README.md"
 requires-python = ">=3.9"

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/rules/human-in-the-loop.md

@@ -40,6 +40,30 @@ When you stop, give the human enough to decide in one read — don't make them d
 Use the `interview-me` skill when an ask is underspecified and you need to extract true intent one
 question at a time, rather than firing a wall of questions.
 
+## Gate the depth of review to reversibility
+
+Not every stop deserves the same ceremony. Before a consequential decision, classify it by how hard it
+is to undo — the **one-way-door vs two-way-door** distinction — and spend review effort proportionally.
+
+Score reversibility across a few dimensions (each: easy → hard to reverse):
+
+- **Undo cost** — can it be reverted with a commit/flag, or does it need a migration/manual cleanup?
+- **Blast radius** — local change vs shared contract, data, or many consumers?
+- **Data effect** — none, or does it mutate/migrate/delete persistent or customer data?
+- **Externalization** — internal only, or published/deployed/sent outside (cacheable, indexable, shipped)?
+- **Commitment** — private, or a public/contractual promise others now depend on?
+
+| Reversibility | Door | Proportional response |
+|---------------|------|-----------------------|
+| **High** (easy to undo, local) | Two-way | Proceed on a stated default; normal review. Don't over-deliberate. |
+| **Medium** | — | Adversarial pass before committing — `doubt-driven-development` or the `devils-advocate` agent (`.claude/rules/quality-gates.md`). |
+| **Low** (hard/irreversible) | One-way | **Stop and ask a human** (this rule), and add a **premortem** (how could this go wrong?), **watch-points** (what to monitor after), and a **reversal plan** before acting. |
+
+Challenge **false irreversibility** too — "we can't change this later" asserted without evidence is
+often a two-way door dressed up as a one-way door; verify before paying one-way-door cost. The point is
+to match scrutiny to stakes, not to gate everything: a clearly-reversible change shouldn't pay for a
+council it doesn't need.
+
 ## Rules
 
 1. **When in doubt, ask.** A cheap question now beats an expensive wrong-direction unwind later. This

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/rules/model-tiers.md

@@ -33,6 +33,43 @@ tier — they are focused specialists/personas, not deep-reasoning orchestrators
 - **Re-map when names/prices change.** Keep the tier *intent* (Critical / Default / Fast); swap the
   concrete alias if Anthropic's model lineup shifts.
 
+## When to escalate a tier
+
+The table above is the *default* assignment. Mid-task, an agent may want to **escalate** to a more
+capable model (or a human asks "should we move this to opus?"). Escalation trades cost for reasoning
+depth, so it must be **justified, not reflexive**.
+
+> **The Iron Law: no escalation without investigation first.** Escalation is never a shortcut for
+> "maybe a smarter model will figure it out." If you can't articulate *why* the current tier is
+> insufficient, escalating is premature — investigate the root cause first.
+
+**Four questions to answer before escalating:**
+
+1. **Understood?** Can I state specifically what reasoning the current tier is missing — is this a
+   *capability* gap or just a *knowledge* gap? (A knowledge gap → gather information, don't escalate.)
+2. **Investigated?** Have I done the systematic work (read the code, traced the data, reproduced the
+   failure) — see `.claude/rules/reasoning-techniques.md` — rather than guessing?
+3. **Right lever?** Is more model capability actually the fix, or is the real problem a wrong approach,
+   a missing requirement (`.claude/rules/human-in-the-loop.md`), or insufficient context?
+4. **Worth it?** Does the stakes/consequence justify the added cost (`.claude/rules/risk-classification.md`)?
+
+**Legitimate triggers:** genuine nuance/judgment (security trade-offs), multi-step reasoning under
+uncertainty (architecture), novel patterns with no precedent, high stakes (production/irreversible),
+or weighing several valid interpretations.
+
+**Anti-rationalizations — these mean STOP and investigate, not escalate:**
+
+| Rationalization | Reality |
+|---|---|
+| "Maybe a smarter model will figure it out" | Thrashing — find the root cause first |
+| "Several attempts already failed" | Suggests a wrong approach, not insufficient capability — question your assumptions |
+| "We're under time pressure" | Urgency doesn't change task complexity; systematic investigation is faster than guess-and-escalate |
+| "Just to be safe / just in case" | False safety — assess the *actual* complexity before spending the capability |
+
+The same discipline governs the **fix-attempt** loop in `.claude/rules/agent-resilience.md` (3-strike
+rule) and the budget-exhaustion escalations in `.claude/rules/quality-gates.md`: investigate, then
+escalate to a tier *or a human* deliberately.
+
 ## Profile cost expectations
 
 Token cost scales with the **profile** (the agent / skill / hook set it installs — see

claude_code_kit-0.41.0/skills/safety-critical-patterns/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: safety-critical-patterns
+description: High-reliability coding lens adapted from NASA's Power of 10 — bounded loops & recursion, assertion density at boundaries/invariants, minimal variable scope, check every return value, restrained metaprogramming, strictest warnings — applied with rigor MATCHED TO CONSEQUENCE (full for money movement, medical, data-integrity, auth, irreversible actions; selective for core business logic; light for scripts/prototypes). Use when writing or reviewing code whose failure is expensive. Do NOT use as a general style/quality pass (use code-review-and-quality) or to scan for complexity to delete (use over-engineering-review) — this is the reliability lens, gated by consequence so it never over-applies to ordinary CRUD.
+---
+
+# Safety-Critical Coding Patterns
+
+> A high-reliability review/authoring lens adapted (stack-agnostic) from NASA JPL's **Power of 10**
+> rules, via the MIT-licensed [`athola/claude-night-market`](https://github.com/athola/claude-night-market)
+> `safety-critical-patterns` skill. The rules are language-neutral *intent*, not C-specific mandates.
+
+## Match rigor to consequence (the gate)
+
+This is the most important rule — apply the rest **proportional to what a failure costs**, never
+uniformly. Use `.claude/rules/risk-classification.md` to place the change:
+
+| Rigor | Apply to |
+|-------|----------|
+| **Full** | Money movement, medical/clinical, data-integrity, authn/authz, anything irreversible |
+| **Selective** | Core business logic, public API handlers, core algorithms |
+| **Light** | Scripts, prototypes, non-critical utilities, throwaway tooling |
+
+Forcing all ten rules onto a CRUD endpoint is itself an over-engineering smell
+(`over-engineering-review`). The point is reliability where reliability is worth paying for.
+
+## The 10 rules (adapted, language-neutral)
+
+1. **Restrict control flow.** Avoid arbitrary jumps; **bound recursion**. Recursion is fine with a
+   provable termination (tail call, bounded depth, tree of known size).
+2. **Fixed loop bounds.** Every loop has a verifiable upper bound. Give a potentially-unbounded loop a
+   safety limit and a reason it terminates.
+   ```python
+   for i in range(min(len(items), MAX_ITEMS)):   # bound is explicit
+       process(items[i])
+   # vs.  while not done:  ...                    # when does this end?
+   ```
+3. **Bound resource acquisition.** Don't allocate without limit on a hot/critical path; pre-size and
+   reuse where allocation failure mid-operation would be unrecoverable (GC languages relax this).
+4. **Keep functions short (~60 lines / one screen).** Cognitive limits are real; long functions hide
+   bugs. Flexible for declarative/config, strict for complex logic.
+5. **Assert boundaries and invariants.** Add defensive assertions for preconditions, postconditions,
+   and the things that "can't happen." Focus on real invariants, not a quota.
+   ```python
+   def transfer(src, dst, amount):
+       assert src != dst, "cannot transfer to same account"
+       assert amount > 0, "amount must be positive"
+       assert src.balance >= amount, "insufficient funds"
+   ```
+6. **Minimal variable scope.** Declare at the narrowest scope; don't hoist state into a wider scope
+   than its use.
+7. **Check every return value and validate every input.** Never ignore a result that can signal
+   failure; never trust an unvalidated parameter. (This is the reliability-side of
+   `agent-guardrails.md`'s "validate inputs.")
+   ```python
+   cfg = parse_config(path)
+   if cfg is None:
+       raise ConfigError(f"failed to parse {path}")   # not: parse_config(path)  # result dropped
+   ```
+8. **Restrain metaprogramming.** Limit macros/decorators/codegen/reflection; they defeat static
+   analysis and obscure control flow. Prefer explicit over magic; document any metaprogramming.
+9. **Discipline indirection & ownership.** Limit levels of indirection; be explicit about who owns and
+   mutates state. Prefer immutable data and clear types over deep optional/pointer chains.
+10. **Compile/lint at the strictest setting from day one.** Turn on all warnings and treat them as
+    errors. (e.g. `ruff --select=ALL` + `mypy --strict`; `tsc --strict`; `-Wall -Werror`; `clippy`.)
+
+## Rules that may not apply
+
+| Rule | Relax when |
+|------|-----------|
+| Bounded recursion | Tree traversal / parser combinators with provably bounded depth |
+| Bounded allocation | GC languages, short-lived processes |
+| ~60-line functions | Declarative config, exhaustive state machines |
+| Restrained indirection | Callbacks, event handlers, strategy patterns are legitimate |
+
+## Reporting violations
+
+Each finding is **grounded** (per `code-review-and-quality`): cite `Rule N`, a `file:line` Location,
+and a verbatim Anchor from that line, plus the issue and a concrete fix. Re-verify the citation before
+reporting.
+
+## Related
+
+- `.claude/rules/risk-classification.md` — sets the consequence tier that gates how much of this to apply
+- `code-review-and-quality` — the general multi-axis review; this is the reliability lens layered on top for high-consequence code
+- `over-engineering-review` — the opposite guard: don't apply full rigor where consequence doesn't warrant it
+- `.claude/rules/testing.md` — assertions complement, never replace, the runnable test for non-trivial logic

claude_code_kit-0.41.0/skills/shell-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: shell-review
+description: Audits shell scripts (bash/POSIX sh) for correctness, safety, and portability — exit-code propagation (set -euo pipefail, pipefail, capture-output-and-status), POSIX-vs-bash portability + shebang choice, safety (quote & brace variables, fail on unset, cd inside a subshell, mktemp + trap cleanup), and structure (library vs executable, main(), shellcheck/shfmt). Use when reviewing or before committing CI / git-hook / build / wrapper shell scripts. Do NOT use for non-shell code (use code-review-and-quality) or to author a brand-new script from a blank file — this is a review lens for existing shell.
+---
+
+# Shell Script Review
+
+> A stack-agnostic shell-audit lens re-derived from the MIT-licensed
+> [`athola/claude-night-market`](https://github.com/athola/claude-night-market) `shell-review` skill
+> (project-specific logging/guard conventions dropped — these are the universal checks). Shell is the
+> one language nearly every repo ships (CI, git hooks, build, wrapper scripts) and the easiest to get
+> subtly wrong, so it earns its own pass. Verify fixes with `shellcheck`.
+
+## When to use
+
+- Reviewing CI/CD pipeline scripts, git-hook scripts, build automation, `run-*.sh` wrappers
+- Before committing any change to a `.sh` file (or a `#!`-shebang script)
+
+**Not for:** non-shell code (→ `code-review-and-quality`); authoring a fresh script from scratch.
+
+## 1. Exit codes — failures must propagate
+
+The default pipeline exit code is the **last** command's, which silently masks earlier failures:
+
+```bash
+# BAD — grep succeeds when it finds lines, hiding a make failure
+if make typecheck 2>&1 | grep -v '^make'; then echo "passed"; fi   # runs even when make failed
+```
+
+- Start scripts with `set -euo pipefail` (`-e` exit on error, `-u` error on unset var, `pipefail`
+  propagate pipeline failures). `set -e` is for executables, not sourced libraries.
+- When you must filter output but keep the status, **capture separately**:
+  ```bash
+  out=$(make typecheck 2>&1) || rc=$?
+  printf '%s\n' "$out" | grep -v '^make' || true
+  exit "${rc:-0}"
+  ```
+- Check the status of commands whose failure matters; don't `cmd | true`-away real errors.
+
+## 2. Portability — match shebang to features used
+
+```bash
+#!/bin/sh             # POSIX — most portable
+#!/usr/bin/env bash   # bash via env — use when you rely on bash features
+```
+
+If the script uses bash-only constructs, the shebang must be bash. Common bash-isms (and POSIX
+alternatives): `[[ … ]]` → `[ … ]`; `(( … ))` → `$(( … ))`; arrays → positional params/files;
+`${var//a/b}` → `sed`; `<<<` here-string → `printf … |`; `<(cmd)` process-sub → temp file; `source` →
+`.`; `function f {}` → `f() {}`. Either restrict to POSIX **or** declare bash in the shebang — don't
+run bash-isms under `#!/bin/sh`.
+
+## 3. Safety patterns
+
+- **Quote and brace variables:** `"${VAR}"`, `"${1}"`, `"${@}"` (not `$VAR`/`$@`) — unquoted
+  expansion word-splits and globs. This is the single most common shell bug.
+- **Require values explicitly:** `: "${CONFIG:?CONFIG must be set}"` instead of branching on unset.
+- **`cd` in a subshell** so a failed `cd` can't run later commands in the wrong directory:
+  `( cd "${dir}" && do_work )`.
+- **Temp files with `mktemp` + `trap … EXIT` cleanup**; never predictable `/tmp/$$` names.
+- **`printf` over `echo`** for anything with backslashes/leading-dash/variable data (`echo` behavior
+  varies across shells).
+- Don't pipe untrusted input into `eval`/`sh`; avoid `curl … | sh`.
+
+## 4. Structure
+
+- **Library vs executable:** a *library* (meant to be sourced) defines functions, sets no `set -e`,
+  and has no execute bit; an *executable* defines `main()`, ends with `main "${@}"`, and is `chmod +x`.
+  Don't give a library the execute bit or a `main`.
+- Keep functions small; give an executable a `usage()`; run `shfmt` for consistent formatting.
+- A sourced library that wasn't loaded should fail loudly at the call site rather than silently
+  no-op.
+
+## 5. Tooling & grounded findings
+
+- **`shellcheck <script>`** is the backstop — run it and treat warnings as findings; many of the above
+  are SC-coded. **`shfmt -d`** for formatting drift.
+- Report each finding **grounded** (per `code-review-and-quality`): `file:line` + a verbatim anchor +
+  the issue + a concrete fix. Re-verify the citation before reporting.
+
+## Output
+
+One finding per line: `path:Lline — <category>: <issue>. Fix: <remediation>.` End with a one-line
+verdict (`N findings: X exit-code, Y safety, Z portability` or `Clean — shellcheck passes`).
+
+## Related
+
+- `code-review-and-quality` — general review; this is the shell-specific lens
+- `ci-cd-and-automation` / `git-workflow-and-versioning` — where most reviewed shell lives (pipelines, hooks)
+- `safety-critical-patterns` — the same "check return values / bound loops" discipline, language-neutral

{claude_code_kit-0.40.0 → claude_code_kit-0.41.0}/src/claude_kit/__init__.py

@@ -7,4 +7,4 @@ Docker): ``claude-kit init`` asks ordered questions and lays down ``CLAUDE.md``
 as a plugin. Extensibility is data-driven via the ``catalog/`` (stacks, profiles, MCP).
 """
 
-__version__ = "0.40.0"
+__version__ = "0.41.0"