claude-code-kit 0.77.0__tar.gz → 0.79.0__tar.gz

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "displayName": "Claude Kit SDLC",
       "source": "./",
       "description": "Evidence-gated SDLC for Claude Code, installed as configuration (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 with a tamper-evident gate ledger, working memory, and a self-improving learnings loop.",
-      "version": "0.77.0",
+      "version": "0.79.0",
       "license": "MIT",
       "keywords": ["sdlc", "agents", "orchestration", "quality-gates", "workflow", "scaffold", "cookiecutter"]
     }

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-kit",
   "displayName": "Claude Kit SDLC",
-  "version": "0.77.0",
+  "version": "0.79.0",
   "description": "Evidence-gated SDLC for Claude Code, installed as configuration (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 a tamper-evident gate ledger, working memory, and a self-improving learnings loop.",
   "author": {
     "name": "Arjunsingh Yadav",

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/CHANGELOG.md

@@ -4,6 +4,163 @@ 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.79.0] — 2026-08-08
+
+**Two ways the installer could destroy a file it had no business touching, and the escape hatch
+that made the richest profile the least targeted one.** All three came out of an external audit of
+the repo. The first two are the kind of bug a scaffolder must not have: it writes into other
+people's projects, so "we only delete our own files" has to be true by construction, not by
+convention.
+
+### Fixed
+
+- **A recorded path in `init-options.json` could reach outside the project root.** The manifest
+  lives *inside* the project being upgraded, which makes it untrusted input — and `upgrade` joins
+  its `files[].path` entries onto the project root before copying, overwriting, and `unlink()`-ing
+  the result. A manifest containing `{"path": "../VICTIM.txt", "owner": "kit"}` made
+  `claude-kit upgrade` delete a file *above* the project, reporting it as
+  `- ../VICTIM.txt (orphan removed)`. `init --defaults` shared the same `_diff_actions` path.
+
+  Paths are now validated where the manifest is parsed (`models.contained_relpath`): absolute,
+  drive-qualified, and `..`-containing paths are refused, and backslashes are normalised first so a
+  Windows-style `..\..\x` cannot slip past a POSIX segment check and then be re-read as a separator
+  by `pathlib`. A rejected path surfaces through the existing corrupt-manifest route, so the
+  operator gets a `FAIL` with a remedy rather than a silent deletion. The orphan loop — the only
+  branch that deletes — additionally re-checks containment at the moment of use
+  (`upgrader._inside`), because a *symlinked* directory inside the project can make a perfectly
+  innocent relative path resolve outside it. Threat model: clone a repo, run `claude-kit upgrade`.
+
+- **`--force` silently deleted user files from kit-owned directories.** `_copy_tree` did an
+  unconditional `shutil.rmtree(dest)` before copying, and it is called on `.claude/rules/`,
+  `.claude/templates/`, `.claude/skills/<name>/` and `.claude/org-packs/<pack>/`. A hand-written
+  `.claude/rules/team-conventions.md` was gone after a `--force` re-init — no backup, no log line,
+  and no coverage from the upgrader's checksum/sidecar machinery, which only protects files the kit
+  itself recorded. The `--force` help text promised only to "overwrite existing CLAUDE.md /
+  settings.json / .mcp.json".
+
+  Files a directory-replacing install will not rewrite are now **moved** into `.claude-kit.bak-N/`
+  — the same convention `upgrade` already uses — mirroring their project-relative path, and the
+  install log names them. The backup directory is created lazily, so a fresh install and the
+  sandbox render used by merge/upgrade still produce none. Overlay and org rules are declared as
+  `also_shipped` because they are written into `.claude/rules/` *after* the core tree is replaced;
+  without that they read as user additions on every re-install, which would fill the backup with
+  kit files and tell the user their content was preserved when none of it was theirs. `--force`'s
+  help text now describes what it actually does.
+
+### Changed
+
+- **`enterprise` enumerates its skills instead of declaring `skills: all`.** `all` meant "every
+  directory under `skills/`", which made the richest profile the least targeted one: resolving
+  **Go + no frontend + no database + enterprise** installed 115 skills / 6.1 MB, among them
+  `alembic-migrations`, `fastapi-service-patterns`, `react-hook-form-zod-patterns` and
+  `dockerfile-frontend` — ~55k lines of content for stacks the project does not use, every one of
+  them competing in the skill picker. 67 skills were reachable *only* through `all`.
+
+  The 25 stack-flavored skills now ride `catalog/stacks.yaml`'s `skills:` union — the mechanism the
+  react and fastapi entries already used — so they install only when that stack is selected. No
+  files moved, no resolver change, and `resolve()` stays branch-free. That same Go selection now
+  resolves to 92 skills with **zero** stack-irrelevant ones; react + fastapi + postgres still gets
+  113. `lean ⊂ standard ⊂ enterprise` still holds, and every skill in the payload is still
+  reachable by some live selection (the two Node ones are gated behind `status: planned`, as
+  intended). This is the "stack-aware skill filter" `docs/skill-audit.md` recommended and then
+  deferred; that document now records the outcome.
+
+  **This changes what an enterprise install contains.** Adding a directory to `skills/` no longer
+  installs it by default — name it in a profile (stack-agnostic) or a `stacks.yaml` union
+  (stack-specific). Existing installs pick the new set up on `claude-kit upgrade`, which backs up
+  anything you edited.
+
+- **The corrupt-manifest message names both causes** — malformed JSON, or a path that is not
+  project-relative — since the fix differs even though the remedy (repair or re-init) does not.
+
+### Added
+
+- `tests/test_containment.py`, `tests/test_scaffold_rescue.py`, `tests/test_skill_relevance.py` —
+  regression coverage for all three, including a guard that no profile may reintroduce
+  `skills: all` and a check that enumerating orphaned no skill.
+
+### Not adopted (deliberately)
+
+- **Removing `object-oriented-design` (464 KB) and `system-design-patterns` (599 KB) from
+  enterprise.** They are interview-prep and engineering-blog digests — ~1 MB, ~17% of the payload —
+  and they are the strongest remaining argument that the skill corpus has drifted from "SDLC kit".
+  But they are stack-agnostic, so the relevance gating this release adds does not reach them, and
+  cutting them is a scope decision about what claude-kit *is*, not a bug fix. Left installed and
+  flagged; the `license-note: ideas absorbed in own words` provenance line appears 278 times across
+  them and deserves a separate look.
+- **`hooks: all`.** Kept. The hook registry is small, closed, and every hook is stack-neutral, so
+  "all of them" is a real statement of intent rather than an accident of directory creation. The
+  header comment in `profiles.yaml` now says why the token is right there and wrong for skills.
+- **Making the gate ledger tamper-evident.** `gate_history` entries are unchained, so a deleted or
+  reordered entry is undetectable, and `_blocking_findings()` reads `open_findings` from the
+  snapshot the agent itself wrote. Both are real, both are out of scope for a fix release, and
+  neither is what the ledger is currently sold as doing.
+
+## [0.78.0] — 2026-08-08
+
+**Two decisions carried out of the 0.77.0 evaluation, one of which only half works.** Both are
+prose changes to shipped payload — no code, no schema, no CLI surface. They are released together
+because they answer the same question from opposite directions: what a rule is *for* when a hook
+already does the job, and what routing prose can make a session do.
+
+### Added
+
+- **`templates/CLAUDE.md` now says: do not perform a coordinator's role yourself — spawn the
+  coordinator.** The failure this addresses is not idleness but a convincing imitation. Measured on
+  the same task with the same agents installed, a session asked directly spawned `developer` and
+  `sdlc-code-reviewer` in sequence — the right leaf work, in the right order — but never spawned
+  `orchestrator`; asked for a security review it dispatched all four sub-scanners in parallel but
+  never spawned `security-reviewer`. The designed behaviour happened; the agent that owns the gate
+  ledger, stage order, lane/wave state and resume snapshot did not. **This works for one of the two
+  coordinators** (F-036, recorded `partially_fixed`, not `fixed`):
+
+  | coordinator | spawned itself | baseline | verdict |
+  |---|---|---|---|
+  | `security-reviewer` | 6/8 | 0/1 | works |
+  | `orchestrator` | 1/8 | 0/1 | does not — still ad-hoc |
+
+  Two wordings, 8 runs each. The combined 4/8 vs 3/8 is one run on n=4 and is noise; the per-agent
+  split is stable across both wordings. The `orchestrator` result reproduces E-060's conclusion —
+  the probe hands the session the orchestrator's own job description and then asks for the work, so
+  adopting the role is close to the reasonable reading of the prompt. Through `/sdlc` it dispatches
+  correctly. **If you want the pipeline, invoke `/claude-kit:sdlc`; do not rely on this paragraph to
+  route you there.**
+
+### Changed
+
+- **`rules/continuity.md` now states why it restates what the hook already does.** Ablation shows
+  `load-continuity.sh` is both necessary *and* sufficient for the file-observable half of the
+  continuity protocol: with the hook on, the behaviour happens whether or not the rule is loaded.
+  That makes the overlap read as dead weight — and deleting it would be wrong. Hooks are opt-out,
+  can be disabled per project, are skipped by harnesses that do not run `SessionStart`, and are the
+  first thing removed when someone is debugging. An install with no hooks still needs the resume
+  contract stated somewhere. The rule is now explicit that the prose is the contract and the hook is
+  one implementation of it, so neither may be deleted on the grounds that the other covers it
+  (E-020) — which is exactly the inference the ablation invites.
+
+### Not adopted (deliberately)
+
+- **A wording that routes through the `sdlc` skill instead of naming the agent.** It fired **0/8** —
+  with the skill installed (125 in the workspace), the `Skill` tool allow-listed, and the paragraph
+  verified present in the workspace `CLAUDE.md`. This is F-110 reproducing inside a fix for a
+  different finding: routing prose cannot delegate to a skill that will not trigger on task-shaped
+  work. It bounds what any instruction of this shape can achieve, so the shipped wording names the
+  agent directly. The skill-shaped variant is not a worse sentence, it is a sentence with no
+  mechanism behind it.
+
+- **Rewording until `orchestrator` self-spawns.** Two wordings at 8 runs each moved
+  `security-reviewer` to 6/8 and left `orchestrator` at 1/8; the split held across both. A third
+  wording was not attempted, because the per-agent stability says the variable is not the wording —
+  it is that the probe's prompt *is* the orchestrator's job description, and E-060 already reached
+  that conclusion once. Shipping a partial fix with the gap named is honest; iterating prose against
+  a probe artefact until the number moves is how a measurement becomes a target. F-036 stays open.
+
+- **F-110 itself.** Skills fire 19/20 on prompts that restate their own description and **0/90** on
+  realistic task-shaped work. Whether skills *ought* to surface unprompted, or are reference
+  material a session reads on demand, is a product decision rather than a defect to patch, and it is
+  unchanged by this release. The 19/20 figure should continue to be read as the easiest possible
+  case.
+
 ## [0.77.0] — 2026-08-04
 
 **The kit stopped fitting in the window it ships into.** Every rule in `.claude/rules/` loaded at

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: claude-code-kit
-Version: 0.77.0
+Version: 0.79.0
 Summary: Evidence-gated SDLC for Claude Code, installed as 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 with a tamper-evident gate ledger, 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

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/catalog/profiles.yaml

@@ -3,7 +3,13 @@
 #
 # Each profile lists agents / skills / gates / hooks. `inherit: <profile>` composes on top of
 # another profile (this profile's lists are unioned with the inherited ones). The special value
-# `all` means "every available item discovered in the payload" (agents/, skills/, hooks/).
+# `all` means "every available item discovered in the payload".
+#
+# `all` is appropriate for `hooks:` — the hook registry is small, closed, and every hook is
+# stack-neutral, so "all of them" is a real statement of intent. It is NOT appropriate for
+# `skills:`: skills are numerous and many are stack-flavored, so `all` silently turned every new
+# directory in skills/ into an enterprise install and put it in the skill picker. Enumerate skills;
+# gate the stack-specific ones through catalog/stacks.yaml's `skills:` union instead.
 #
 # ORDER CONVENTION for `gates:` — gates are the one list where order is data: the resolved list
 # lands execution-ordered in stack-catalog.snapshot.yaml and `claude-kit pipeline close-gate`
@@ -128,6 +134,70 @@ profiles:
       - auditor
       - incident-responder
       - risk-classifier
-    skills: all
+    # ENUMERATED, not `all`. `skills: all` used to mean "every directory in skills/", which made the
+    # richest profile the least targeted one: a Go service with no frontend and no database still
+    # received React, FastAPI and Alembic skills — ~55k lines of content for a stack the project
+    # does not use, all of it competing in the skill picker. Everything stack-flavored now rides
+    # catalog/stacks.yaml's `skills:` union instead (installed only when that stack is selected),
+    # and what remains here is what an enterprise pipeline needs regardless of stack.
+    #
+    # Adding a skill to the payload therefore no longer installs it by default — name it in a
+    # profile (stack-agnostic) or in a stacks.yaml union (stack-specific). That is the point:
+    # membership is a decision, not a side effect of creating a directory.
+    skills:
+      # Operate / run: the stages enterprise adds over standard (pipeline-green, observability-ready).
+      - ci-cd-and-automation
+      - observability-and-logging
+      - otel-tracing
+      - grafana-dashboards-and-alerts
+      - kubectl-operations
+      - kubernetes-workload-hardening
+      - containerization-and-deployment
+      - docker-compose
+      - docker-shared
+      - gcp-cloud-run-github-actions
+      - cron-and-scheduled-jobs
+      # Design / architecture reference used by technical-architect and the auditor.
+      - design-patterns-and-conventions
+      - distributed-systems-patterns
+      - object-oriented-design
+      - system-design-patterns
+      - safety-critical-patterns
+      - multi-tenancy-patterns
+      - edge-to-service-trust-boundary
+      - auth-and-rbac
+      - api-pagination-filtering-sorting
+      - graphql-patterns
+      - redis-caching-patterns
+      - notifications-and-messaging
+      - file-export-and-reporting
+      # Change management: the auditor / risk-classifier surface.
+      - dependency-verification
+      - deprecation-and-migration
+      - modernization-and-migration
+      - library-review
+      - shell-review
+      # Data / eventing platforms.
+      - kafka-config-driven
+      - temporal-config-driven
+      - temporal-developer
+      - data-engineering-bigquery-gcs
+      - gcs-file-storage-patterns
+      # LLM-product engineering.
+      - anthropic-vertex-integration
+      - langfuse-llm-tracing
+      - llm-caching-strategies
+      - llm-gateway-and-routing
+      - llm-inference-optimization
+      - rag-and-model-tuning
+      # Delivery workflow.
+      - sprint
+      - backlog
+      - archive-sprint
+      - triage
+      - shipping-and-launch
+      - consolidate-learnings
+      - doc-consolidation
+      - playwright-verification
     gates: [spec-complete, em-approved, code-review, build-green, contract-clear, test-coverage, security-clear, pipeline-green, observability-ready, acceptance]
     hooks: all

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/catalog/stacks.yaml

@@ -34,7 +34,25 @@ frontend:
       # frontend-specific (component/hook tests, client-side data fetching, headed-browser QA), so
       # they install only when a frontend exists. Backend testing is covered by the universal
       # test-driven-development core skill.
-      skills: [frontend-ui-engineering, component-design, ui-ux-design, unit-test, api-integration, manual-test]
+      #
+      # The library-specific patterns below follow the same rule: a project with no React frontend
+      # has no use for Zustand or TanStack Query docs, so they are gated here rather than named by a
+      # profile. This is what keeps the profiles stack-agnostic while the skills stay concrete.
+      skills:
+        - frontend-ui-engineering
+        - component-design
+        - ui-ux-design
+        - unit-test
+        - api-integration
+        - manual-test
+        - frontend-repo-architecture
+        - design-system-ops
+        - radix-tailwind-component-patterns
+        - react-hook-form-zod-patterns
+        - tanstack-react-query-patterns
+        - vitest-rtl-msw-patterns
+        - zustand-state-patterns
+        - dockerfile-frontend
       stack_dir: frontend/react
       commands:
         install: "npm install"
@@ -71,7 +89,20 @@ backend:
           label: "FastAPI"
           overlay_rules: [fastapi-patterns.md]
           overlay_agents: []
-          skills: [api-and-interface-design]
+          # Python/FastAPI-specific skills are gated here, not named by a profile: a Go or Node
+          # project has no use for Alembic migrations or Pydantic schema patterns, and shipping
+          # them anyway is what made `skills: all` install ~55k lines of irrelevant content.
+          skills:
+            - api-and-interface-design
+            - backend-repo-architecture
+            - fastapi-service-patterns
+            - pydantic-schema-patterns
+            - python-dao-and-database
+            - alembic-migrations
+            - async-python-patterns
+            - configargparse-yaml-env-layering
+            - testing-conventions
+            - dockerfile-backend
           stack_dir: backend/python/fastapi
           commands:
             install: "pip install -e '.[dev]'"
@@ -91,6 +122,7 @@ backend:
         express:
           label: "Express"
           status: planned
+          skills: [backend-repo-architecture, node-express-service, node-objection-knex, dockerfile-backend]
           stack_dir: backend/node/express
     go:
       label: "Go"
@@ -100,7 +132,7 @@ backend:
           label: "net/http (stdlib)"
           overlay_rules: [go-patterns.md]
           overlay_agents: []
-          skills: [api-and-interface-design]
+          skills: [api-and-interface-design, backend-repo-architecture, dockerfile-backend]
           stack_dir: backend/go/net-http
           commands:
             install: "go mod download"

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/docs/skill-audit.md

@@ -62,7 +62,22 @@ Measured on a `react + fastapi + postgres` project with `--scope individual`:
 
 ## Finding: Enterprise Over-Install of Stack-Collection Skills
 
-The enterprise profile uses `skills: all` in `catalog/profiles.yaml`, which installs **every skill in the payload** — including all 51 stack-collection skills, regardless of whether the project selected those stacks.
+> **Status: resolved.** `skills: all` is gone. The enterprise profile now enumerates its skills, and
+> the stack-flavored ones are gated through `catalog/stacks.yaml`'s `skills:` union — the
+> "stack-aware skill filter" this audit recommended below, built on the mechanism the react and
+> fastapi stacks already used rather than a new `stack-relevant` token. Measured after the change:
+>
+> | selection | skills | on-disk |
+> |---|---|---|
+> | enterprise, react + fastapi + postgres | 113 | ~5.6 MB |
+> | enterprise, Go, no frontend, no database | 92 | ~4.6 MB |
+>
+> The Go project no longer receives React, FastAPI, Alembic, Pydantic, Zustand or TanStack content
+> — 0 stack-irrelevant skills, down from 32. `tests/test_skill_relevance.py` pins this, including a
+> guard that no profile may reintroduce `skills: all`. The rest of this section is the original
+> finding, kept as the record of why the change was made.
+
+The enterprise profile used `skills: all` in `catalog/profiles.yaml`, which installed **every skill in the payload** — including all 51 stack-collection skills, regardless of whether the project selected those stacks.
 
 **Impact:**
 
@@ -107,7 +122,7 @@ The following skills are candidates for **review** (not deletion). They plausibl
 
 ## Recommendations
 
-### Default (this audit takes)
+### Default (this audit took) — since superseded
 
 **Leave `catalog/profiles.yaml` as-is and document the trade-off.**
 
@@ -115,6 +130,14 @@ The following skills are candidates for **review** (not deletion). They plausibl
 - The on-demand activation model bounds the context cost of the extra files.
 - Document the enterprise skill footprint in the profile description so the trade-off is visible before a user picks it.
 
+> **Superseded.** Option 1 below ("stack-aware skill filter") was implemented instead, in the form
+> the constraints already allowed: no new `stack-relevant` token and no resolver change — the
+> stack-flavored skills simply moved into the `skills:` unions in `catalog/stacks.yaml` that the
+> react and fastapi entries were already using, and enterprise enumerates the rest. The
+> "deliberate choice for multi-stack orgs" argument did not survive contact with the numbers: the
+> cost fell on every *single*-stack enterprise user, which is most of them, and a multi-stack org
+> can still name any skill it wants in a profile.
+
 ### Optional (recommend evaluating, not implemented here)
 
 **Evaluate a config-level opt-in that installs only stack-relevant collection skills.**

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-code-kit"
-version = "0.77.0"
+version = "0.79.0"
 description = "Evidence-gated SDLC for Claude Code, installed as 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 with a tamper-evident gate ledger, working memory, and a self-improving learnings loop."
 readme = "README.md"
 requires-python = ">=3.9"

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/rules/continuity.md

@@ -22,6 +22,15 @@ When a CONTINUITY entry under **Mistakes & Learnings** is durable (a correction,
 - **Seed:** `.claude/CONTINUITY.template.md` — committed. The `load-continuity.sh` SessionStart hook copies the template to the live file if the live file is missing, then prints it into context.
 - Never commit the live file. Never store secrets, tokens, or credentials in it.
 
+**This rule deliberately restates what the hook already does.** Ablation shows `load-continuity.sh`
+is both necessary and sufficient for the file-observable half of this protocol: with the hook on,
+the behaviour happens whether or not this rule is loaded. That makes the overlap look like dead
+weight, and it is kept anyway — hooks are opt-out, can be disabled per project, are skipped by
+harnesses that do not run SessionStart, and are the first thing removed when someone is debugging.
+An install with no hooks still needs the resume contract to be *stated somewhere*, so the prose is
+defence-in-depth rather than duplication. Read it as the contract; the hook is one implementation
+of it, not the only one. Do not delete either on the grounds that the other covers it.
+
 ## Resume snapshot (`.claude/state/pipeline-snapshot.json`)
 
 `CONTINUITY.md` is the human-readable scratchpad; for a pipeline run it is paired with a small **structured snapshot** so a later session can re-enter precisely. The Orchestrator writes/updates it at every stage transition (alongside the `PIPELINE:` line it mirrors into **Current Phase**). It is gitignored runtime state under `.claude/state/` — created by the installer and ensured by the `load-continuity` SessionStart hook.

{claude_code_kit-0.77.0 → claude_code_kit-0.79.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.77.0"
+__version__ = "0.79.0"

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/src/claude_kit/cli.py

@@ -215,7 +215,11 @@ def init(
     force: bool = typer.Option(
         False,
         "--force",
-        help="overwrite existing CLAUDE.md / settings.json / .mcp.json",
+        help=(
+            "overwrite mode: replace CLAUDE.md / settings.json / .mcp.json and rebuild the "
+            "kit-owned trees (rules/, skills/, templates/). Your own files in those trees are "
+            "moved to .claude-kit.bak-N/, not deleted. Omit --force to merge instead."
+        ),
     ),
     dry_run: bool = typer.Option(
         False,

{claude_code_kit-0.77.0 → claude_code_kit-0.79.0}/src/claude_kit/models.py

@@ -9,6 +9,7 @@ documentation rule and keeps ``init-options.json`` round-trippable for ``validat
 from __future__ import annotations
 
 from dataclasses import asdict, dataclass, field
+from pathlib import PurePosixPath
 from typing import Any
 
 #: Schema version of the persisted ``.claude/config/init-options.json`` document.
@@ -194,12 +195,56 @@ class ResolvedPlan:
     detected_commands: dict[str, str] | None = None
 
 
+def contained_relpath(raw: str) -> str:
+    """Validate ``raw`` as a project-relative POSIX path and return it normalised.
+
+    ``init-options.json`` lives inside the project being upgraded, so its ``files[].path`` entries
+    are untrusted input: :mod:`claude_kit.upgrader` joins them onto the project root and then
+    copies, overwrites, and *unlinks* the result. A path that escapes the root (``../../id_rsa``)
+    or is absolute (``/etc/passwd``) would let a hand-edited — or hostile — manifest reach files
+    outside the project. Rejecting them here means every consumer (``validate``, ``diff``,
+    ``upgrade``, ``doctor``) inherits the guarantee from one place, at parse time, before any
+    filesystem call. ``_read_init_options`` already renders the resulting :class:`ValueError` as a
+    ``corrupt: <detail>`` manifest, which is the correct signal.
+
+    Backslashes are normalised to ``/`` first so a Windows-style ``..\\..\\x`` cannot slip past a
+    POSIX-only segment check and then be re-interpreted as a separator by ``pathlib`` on Windows.
+
+    Args:
+        raw: The candidate path string as read from the manifest.
+
+    Returns:
+        The path in normalised POSIX form.
+
+    Raises:
+        ValueError: If the path is empty, absolute, drive-qualified, or contains a ``..`` segment.
+    """
+    text = str(raw).replace("\\", "/").strip()
+    if not text:
+        raise ValueError("file record has an empty path")
+    pure = PurePosixPath(text)
+    if pure.is_absolute() or text.startswith("/"):
+        raise ValueError(
+            f"file record path must be project-relative, got absolute {raw!r}"
+        )
+    if len(text) > 1 and text[1] == ":":
+        raise ValueError(
+            f"file record path must be project-relative, got drive-qualified {raw!r}"
+        )
+    if ".." in pure.parts:
+        raise ValueError(f"file record path escapes the project root: {raw!r}")
+    return pure.as_posix()
+
+
 @dataclass
 class FileRecord:
     """A single installed file tracked in ``init-options.json`` for safe upgrades.
 
+    The ``path`` is validated on construction by :func:`contained_relpath` — it must stay inside
+    the project root, because the upgrader resolves it against that root and may delete the result.
+
     Attributes:
-        path: Path relative to the project root (POSIX separators).
+        path: Path relative to the project root (POSIX separators, no ``..``).
         sha256: Hex SHA-256 of the file contents at install time.
         owner: One of ``"kit"`` (refreshed on upgrade), ``"overlay"`` (follows the selection),
             or ``"user-editable"`` (never clobbered).
@@ -209,6 +254,10 @@ class FileRecord:
     sha256: str
     owner: str
 
+    def __post_init__(self) -> None:
+        """Normalise and containment-check :attr:`path`."""
+        self.path = contained_relpath(self.path)
+
     def to_dict(self) -> dict[str, str]:
         """Return a JSON-serialisable mapping of this record."""
         return asdict(self)