chore(deps): adopt hybrid Renovate and Dependabot ownership

.github/README.md

@@ -17,7 +17,7 @@
 
 ## About the `.github` Repository
 
-The `.github` repository is a [special GitHub repository](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file) that serves as the **organization-wide configuration hub**. Files placed here apply as defaults across all repositories in the [Z-Shell](https://github.com/z-shell) organization, without needing to duplicate them into every individual repository.
+The `.github` repository is a [special GitHub repository](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file) and the **organization-wide configuration hub**. GitHub inherits supported community health files and templates from here; reusable actions, workflow templates, Renovate policy, ADRs, and runbooks remain shared resources that repositories or maintainers reference explicitly.
 
 ### What Makes It Special
 
@@ -29,7 +29,7 @@ The `.github` repository is a [special GitHub repository](https://docs.github.co
 | **Agent Memory Protocol**          | `.github/AGENT_MEMORY.md` defines the GitHub-native handoff workflow used to keep cross-LLM and cross-repository progress visible.                                                                                                        |
 | **Reusable Composite Actions**     | The `actions/` directory hosts [composite actions](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) that any org repository can reference via `uses: z-shell/.github/actions/<name>@main`.                |
 | **Workflow Templates**             | The `workflow-templates/` directory provides [starter workflows](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) available in every org repository under **Actions > New workflow**. |
-| **Shared Dependency Config**       | `renovate-config.json` defines a shared [Renovate](https://docs.renovatebot.com/) preset that org repositories can extend for consistent automated dependency updates.                                                                    |
+| **Shared Dependency Config**       | `renovate-config.json` defines the shared [Renovate](https://docs.renovatebot.com/) preset for routine version updates; GitHub Dependabot retains alerts and security updates.                                                            |
 
 > **Note:** The `.github` repository must be **public** for default community health files to apply across the organization.
 
@@ -46,8 +46,7 @@ The `.github` repository is a [special GitHub repository](https://docs.github.co
 | [`profile/`](../profile/)                         | Organization profile — the README and visual assets displayed on the [org page](https://github.com/z-shell) |
 | [`actions/`](../actions/)                         | Reusable composite GitHub Actions shared across all org repositories                                        |
 | [`workflow-templates/`](../workflow-templates/)   | Starter workflow templates available in the **Actions > New workflow** tab                                  |
-| [`metrics/`](../metrics/)                         | Auto-generated organization metrics and analytics                                                           |
-| [`renovate-config.json`](../renovate-config.json) | Shared Renovate bot preset for dependency updates                                                           |
+| [`renovate-config.json`](../renovate-config.json) | Shared Renovate preset for routine dependency version updates                                               |
 
 ### Community Health Files
 
@@ -92,20 +91,26 @@ steps:
 
 Starter workflows available in every org repository under **Actions > New workflow**:
 
-| Template        | Description                                            |
-| --------------- | ------------------------------------------------------ |
-| Trunk           | Trunk code-quality workflow                            |
-| Zsh CI          | Starter Zsh CI workflow                                |
-| Rclone Action   | File sync with rclone                                  |
-| Project Tracker | Adds `meta:org-tracked` issues to the org-wide tracker |
+| Template      | Description                 |
+| ------------- | --------------------------- |
+| Trunk         | Trunk code-quality workflow |
+| Zsh CI        | Starter Zsh CI workflow     |
+| Rclone Action | File sync with rclone       |
 
 Label definitions live in [`./lib/labels.yml`](lib/labels.yml) and should be applied through org maintenance scripts or API-driven automation, not via a generic starter workflow template.
 
-Tracker and project automation are documented in [`../runbooks/project-tracker.md`](../runbooks/project-tracker.md). Project 28 is the org-wide tracker, and issues labelled `meta:org-tracked` should be added there automatically by either the Project v2 built-in workflow or the repository workflow fallback.
+Task tracking is documented in [`../runbooks/project-tracker.md`](../runbooks/project-tracker.md).
 
-## Renovate
+## Dependency Management
 
-Shared [Renovate](https://docs.renovatebot.com/) preset for automated dependency updates. Reference from any org repository:
+Z-Shell separates routine maintenance from security remediation:
+
+- [Renovate](https://docs.renovatebot.com/) owns routine dependency version updates.
+- GitHub Dependabot owns dependency graph alerts and security update pull requests.
+
+Repositories must not configure both bots for routine version updates. Renovate
+discovers the shared organization preset automatically during onboarding, or a
+repository can reference it explicitly:
 
 ```json
 {
@@ -114,6 +119,9 @@ Shared [Renovate](https://docs.renovatebot.com/) preset for automated dependency
 }
 ```
 
+See [`../runbooks/dependency-management.md`](../runbooks/dependency-management.md)
+for onboarding, validation, migration, and rollback.
+
 ---
 
 ## Common Use Cases
@@ -123,17 +131,18 @@ This repository is the right place for any **organization-level** configuration:
 - **Adding a new default issue/PR template** — add it to `.github/ISSUE_TEMPLATE/`
 - **Updating agent instructions, ADRs, runbooks, or patterns** — edit `AGENTS.md`, `decisions/`, `runbooks/`, or `PATTERNS.md`
 - **Defining weekly review, ADR, or release coordination workflows** — add or update the relevant file under `runbooks/`
-- **Recording cross-agent progress** — follow `.github/AGENT_MEMORY.md` and keep active state in issues, PRs, and the Z-Shell Tracker
-- **Configuring tracker auto-add** — follow `../runbooks/project-tracker.md`
+- **Recording cross-agent progress** — follow `.github/AGENT_MEMORY.md` and keep active state in issues, pull requests, and Linear
+- **Managing organization task tracking** — follow `../runbooks/project-tracker.md`
 - **Updating the shared label set** — edit `.github/lib/labels.yml` and roll it out via the org's maintenance automation
 - **Cleaning legacy labels** — follow `../runbooks/labels.md` before deleting labels from live repositories
 - **Creating a reusable CI action** — add a composite action under `actions/<name>/action.yml`
 - **Providing a starter workflow** — add `.yml` + `.properties.json` to `workflow-templates/`
 - **Updating the organization profile** — edit `profile/README.md` or add assets to `profile/img/`
 - **Changing contribution or security policies** — edit the corresponding file in `.github/`
-- **Updating shared Renovate config** — edit `renovate-config.json`
+- **Updating dependency automation** — edit `renovate-config.json` and follow `../runbooks/dependency-management.md`
 
-For repository-specific overrides, add the same file to that repository directly — it will take precedence over the defaults from here.
+For a repository-specific Renovate exception, add a minimal `renovate.json` that
+extends the organization preset and contains only the required override.
 
 ## Links
 

AGENTS.md

@@ -25,15 +25,15 @@ The broad shapes are:
 
 Use the right home for each kind of knowledge:
 
-| Kind of information                | Source of truth                                       |
-| ---------------------------------- | ----------------------------------------------------- |
-| Active work, blockers, next steps  | GitHub issues, pull requests, and Linear |
-| Private organizational heuristics  | `memory/` folder in the root meta-workspace           |
-| Durable architectural decisions    | `decisions/` in this repo                             |
-| Cross-repo operational procedures  | `runbooks/` in this repo                              |
-| Reusable implementation idioms     | `PATTERNS.md` in this repo                            |
-| Long-form user and maintainer docs | `wiki/` where practical                               |
-| Local LLM memory                   | Optional cache only, never the only record            |
+| Kind of information                | Source of truth                             |
+| ---------------------------------- | ------------------------------------------- |
+| Active work, blockers, next steps  | GitHub issues, pull requests, and Linear    |
+| Private organizational heuristics  | `memory/` folder in the root meta-workspace |
+| Durable architectural decisions    | `decisions/` in this repo                   |
+| Cross-repo operational procedures  | `runbooks/` in this repo                    |
+| Reusable implementation idioms     | `PATTERNS.md` in this repo                  |
+| Long-form user and maintainer docs | `wiki/` where practical                     |
+| Local LLM memory                   | Optional cache only, never the only record  |
 
 For handoffs, follow `.github/AGENT_MEMORY.md`.
 
@@ -54,6 +54,7 @@ When working in z-shell repositories, optimize for:
 - **Commits and PR titles:** Conventional Commits. See `decisions/0003-conventional-commits.md`.
 - **Documentation placement:** keep long-form docs in the wiki when practical; keep repo-local docs focused on policy, workflow, and source-adjacent guidance.
 - **Workflow files:** follow the org workflow conventions and keep permissions explicit, actions pinned, and concurrency defined.
+- **Dependency updates:** Renovate owns routine version updates; GitHub Dependabot owns vulnerability alerts and security updates. See `runbooks/dependency-management.md`.
 
 ## Before editing
 
@@ -96,6 +97,7 @@ For recurring organization workflows, prefer the runbooks and keep the first pas
 - weekly org review: `runbooks/org-review.md`
 - issue and PR triage: `runbooks/triage.md`
 - label maintenance: `runbooks/labels.md`
+- dependency management: `runbooks/dependency-management.md`
 - project tracker automation: `runbooks/project-tracker.md`
 - new-repository bootstrap: `runbooks/new-repository.md`
 - ADR drafting: `runbooks/adr.md`
@@ -139,6 +141,7 @@ Do not silently work around drift. Open or update an issue in `z-shell/.github`,
 - `decisions/`
 - `runbooks/org-review.md`
 - `runbooks/adr.md`
+- `runbooks/dependency-management.md`
 - `runbooks/labels.md`
 - `runbooks/new-repository.md`
 - `runbooks/project-tracker.md`

decisions/0004-dependabot-unification.md

@@ -4,7 +4,7 @@
 - **Date:** 2026-05-20
 - **Deciders:** ss-o, Gemini CLI
 - **Supersedes:** None
-- **Superseded by:** None
+- **Superseded by:** `decisions/0012-hybrid-dependency-management.md`
 
 ## Context
 

decisions/0012-hybrid-dependency-management.md

@@ -0,0 +1,114 @@
+# 12. Split Dependency Updates Between Renovate and Dependabot
+
+- **Status:** ACCEPTED
+- **Date:** 2026-06-21
+- **Deciders:** ss-o
+- **Supersedes:** `decisions/0004-dependabot-unification.md`
+- **Superseded by:** None
+
+## Context
+
+ADR 0004 standardized dependency management on Dependabot to remove a mixed,
+inconsistent setup. The decision simplified administration, but routine version
+updates still require a separate `.github/dependabot.yml` in every repository.
+Those files have drifted across the organization in enabled ecosystems,
+schedules, grouping, and target branches.
+
+Z-Shell has more than 90 repositories spanning GitHub Actions, npm, Docker, Go,
+Zsh plugins, documentation, and dependency references embedded in files that
+native package managers do not always cover. The organization needs both:
+
+- GitHub-native vulnerability detection and remediation; and
+- centrally governed, flexible routine version maintenance.
+
+Running Renovate and Dependabot for the same routine updates would recreate the
+original fragmentation and add duplicate pull requests, lock-file conflicts,
+and unnecessary CI usage.
+
+## Decision
+
+Adopt a hybrid model with non-overlapping ownership:
+
+1. **GitHub Dependabot owns security:**
+   - dependency graph;
+   - Dependabot alerts;
+   - Dependabot security update pull requests.
+2. **Renovate owns routine version updates:**
+   - GitHub Actions;
+   - package-manager dependencies and lock files;
+   - Docker images;
+   - Go modules;
+   - explicitly configured custom dependency references.
+3. **No overlapping routine updates:** a repository covered by Renovate must
+   not retain a `.github/dependabot.yml` that creates routine version-update
+   pull requests.
+4. **Central preset:** routine update policy lives in
+   `z-shell/.github/renovate-config.json`. Repositories use automatic
+   organization preset discovery or explicitly extend
+   `local>z-shell/.github:renovate-config`.
+5. **Conservative defaults:** the shared preset uses weekly scheduling, a
+   minimum release age, grouped updates, semantic commits, and no global
+   automerge.
+6. **Repository exceptions stay local:** target branches, custom managers, or
+   specialized grouping belong in a small repository `renovate.json`.
+
+## Rollout and rollback
+
+Migration is staged per repository:
+
+1. Confirm the Renovate GitHub App can access the repository.
+2. Confirm Renovate reads the shared preset and processes the repository.
+3. Confirm the dependency graph, Dependabot alerts, and security updates remain
+   enabled in GitHub settings.
+4. Remove `.github/dependabot.yml` to stop overlapping routine updates.
+
+If Renovate coverage is unavailable or fails, restore the repository's
+Dependabot version-update configuration until coverage is healthy. A duplicate
+routine update from both bots is a policy defect and must be resolved by
+disabling the Dependabot version-update entry.
+
+## Consequences
+
+### Positive
+
+- One organization preset controls routine update policy.
+- GitHub remains the native authority for vulnerability alerts and fixes.
+- Renovate supplies broader manager coverage, custom managers, release-age
+  controls, grouping, and a Dependency Dashboard.
+- Explicit ownership prevents duplicate update pull requests.
+- Repository-specific configuration is limited to real exceptions.
+
+### Negative / costs
+
+- The Renovate GitHub App becomes an additional organization integration.
+- App coverage and shared-preset validation must be monitored.
+- Migration requires checking each repository before removing Dependabot
+  version updates.
+- Maintainers must understand that deleting `dependabot.yml` does not disable
+  alerts or security updates configured in GitHub settings.
+
+### Neutral
+
+- Dependency pull requests still rely on repository CI and review policy.
+- Security settings remain organization or repository settings rather than
+  files inherited from the `.github` repository.
+
+## Alternatives considered
+
+1. **Dependabot only:** Rejected because configuration remains duplicated and
+   has already drifted, while coverage and customization are narrower.
+2. **Renovate only:** Rejected because GitHub already provides native
+   vulnerability alerts and security remediation without granting an external
+   app responsibility for the entire security path.
+3. **Both tools for routine updates:** Rejected because it produces duplicate
+   pull requests, conflicting lock-file changes, excess CI usage, and ambiguous
+   ownership.
+
+## References
+
+- [Issue #452 — Migrate repositories to hybrid Renovate ownership](https://github.com/z-shell/.github/issues/452)
+- `decisions/0004-dependabot-unification.md`
+- `runbooks/dependency-management.md`
+- `renovate-config.json`
+- [Renovate configuration presets](https://docs.renovatebot.com/config-presets/)
+- [GitHub Dependabot security updates](https://docs.github.com/en/code-security/concepts/supply-chain-security/dependabot-security-updates)

renovate-config.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "description": "Z-Shell organization preset for routine dependency version updates",
+  "extends": ["config:best-practices", ":semanticCommits"],
+  "timezone": "UTC",
+  "schedule": ["* 0-4 * * 1"],
+  "minimumReleaseAge": "3 days",
+  "dependencyDashboard": true,
+  "dependencyDashboardTitle": "Dependency Dashboard",
+  "labels": ["type:maintenance", "area:dependencies"],
+  "prConcurrentLimit": 5,
+  "prHourlyLimit": 2,
+  "automerge": false,
+  "packageRules": [
+    {
+      "description": "Group non-major updates by package manager",
+      "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
+      "groupName": "{{manager}} non-major updates",
+      "groupSlug": "{{manager}}-non-major"
+    },
+    {
+      "description": "Group non-major GitHub Actions updates",
+      "matchManagers": ["github-actions"],
+      "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
+      "groupName": "github actions non-major updates",
+      "groupSlug": "github-actions-non-major"
+    }
+  ]
+}

renovate.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["local>z-shell/.github:renovate-config"]
+}