feat: deploy-status and prepare-rollback agent skills

.agents/skills/deploy-status/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: deploy-status
+description: Fetch and summarise the gate status for a homelab-deploy pull request. Reports each of the four required checks and whether the PR is merge-ready.
+---
+
+# deploy-status skill
+
+## Purpose
+
+Fetch and summarise the gate status for a homelab-deploy pull request.
+Reports each of the four required checks and whether the PR is merge-ready.
+
+## Usage
+
+```
+deploy-status --pr <number> [--repo homelab-deploy]
+```
+
+## What it does
+
+1. Resolves the PR head SHA.
+2. Lists check runs for that SHA.
+3. Downloads gate-summary artifacts (SC-4) from the associated Pipeline Complete run.
+4. Returns a structured summary:
+   - `gates[]` — one entry per required check: Compose Gate, Leak Scan,
+     Stack Integration Gate, Pipeline Complete.
+   - `merge_ready` — true only when Pipeline Complete is "pass" AND all gates pass.
+   - `blocker` — name of the first non-pass gate, or null.
+
+## Authoritative source
+
+`Pipeline Complete` is the authoritative merge-readiness signal.
+Do not infer merge-readiness from individual gate conclusions alone.
+
+## Limitations
+
+- Read-only. Never merges, approves, or enqueues.
+- Requires `GITHUB_TOKEN` env var with `contents:read` + `actions:read`.
+- Stale artifacts (force-pushed head): always uses latest-head-SHA artifacts.
+
+## Edge cases
+
+- Missing artifact: gate status shown as "pending" or "missing"; not an error.
+- Merge-queue vs PR-head drift: always uses PR head SHA, not merge_group SHA.
+- Tag re-pushed: latest artifact by created_at wins.

.agents/skills/prepare-rollback/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: prepare-rollback
+description: Prepare a rollback branch that pins one service to a prior artifact version. Returns a COMPARE URL for human review. NEVER merges or approves.
+---
+
+# prepare-rollback skill
+
+## Purpose
+
+Prepare a rollback branch that pins one service to a prior artifact version.
+Returns a COMPARE URL for human review. NEVER merges or approves.
+
+## Usage
+
+```
+prepare-rollback \
+  --service     <unit-name> \
+  --prior-tag   <semver-tag> \
+  --reason      "<short description>" \
+  --alert-url   "<github issue or alert URL>"
+```
+
+## What it does
+
+1. Asserts no privileged credentials in environment (RELEASE_APP_PRIVATE_KEY,
+   KUBECONFIG, VAULT_TOKEN, ACTIONS_ID_TOKEN_REQUEST_TOKEN).
+2. Checks App key age ≤ 90 days from SECURITY.md (fails loudly if stale).
+3. Resolves the artifact digest for `prior-tag` from GHCR.
+4. Creates branch `rollback/<service>/<prior-tag>` from main HEAD.
+5. Updates `registry/<service>.yaml` — sets `spec.artifact.digest` to prior digest.
+6. Appends an INCIDENTS.md entry.
+7. Returns: `{ rollback_branch, rollback_pr (COMPARE URL), merged: false }`.
+
+## Boundary
+
+This skill NEVER:
+- Opens a PR (returns COMPARE URL only — human must open the PR).
+- Merges, approves, or queues a PR.
+- Holds RELEASE_APP_PRIVATE_KEY, kubeconfig, Vault token, or OIDC token.
+
+## Required permissions
+
+`GITHUB_TOKEN` with `contents:write` for homelab-deploy (scoped App token via
+owner-controlled path — not a personal access token).
+
+## Edge cases
+
+- Key age > 90d: fails with rotation instructions before any mutation.
+- `rollbackTargetRetention.acknowledged` not set: fails before branch creation.
+- Tag re-pushed: uses digest resolution (not tag timestamp) for the prior version.

.claude/skills/deploy-status/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: deploy-status
+description: Fetch and summarise the gate status for a homelab-deploy pull request. Reports each of the four required checks and whether the PR is merge-ready.
+---
+
+# deploy-status skill
+
+## Purpose
+
+Fetch and summarise the gate status for a homelab-deploy pull request.
+Reports each of the four required checks and whether the PR is merge-ready.
+
+## Usage
+
+```
+deploy-status --pr <number> [--repo homelab-deploy]
+```
+
+## What it does
+
+1. Resolves the PR head SHA.
+2. Lists check runs for that SHA.
+3. Downloads gate-summary artifacts (SC-4) from the associated Pipeline Complete run.
+4. Returns a structured summary:
+   - `gates[]` — one entry per required check: Compose Gate, Leak Scan,
+     Stack Integration Gate, Pipeline Complete.
+   - `merge_ready` — true only when Pipeline Complete is "pass" AND all gates pass.
+   - `blocker` — name of the first non-pass gate, or null.
+
+## Authoritative source
+
+`Pipeline Complete` is the authoritative merge-readiness signal.
+Do not infer merge-readiness from individual gate conclusions alone.
+
+## Limitations
+
+- Read-only. Never merges, approves, or enqueues.
+- Requires `GITHUB_TOKEN` env var with `contents:read` + `actions:read`.
+- Stale artifacts (force-pushed head): always uses latest-head-SHA artifacts.
+
+## Edge cases
+
+- Missing artifact: gate status shown as "pending" or "missing"; not an error.
+- Merge-queue vs PR-head drift: always uses PR head SHA, not merge_group SHA.
+- Tag re-pushed: latest artifact by created_at wins.

.claude/skills/prepare-rollback/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: prepare-rollback
+description: Prepare a rollback branch that pins one service to a prior artifact version. Returns a COMPARE URL for human review. NEVER merges or approves.
+---
+
+# prepare-rollback skill
+
+## Purpose
+
+Prepare a rollback branch that pins one service to a prior artifact version.
+Returns a COMPARE URL for human review. NEVER merges or approves.
+
+## Usage
+
+```
+prepare-rollback \
+  --service     <unit-name> \
+  --prior-tag   <semver-tag> \
+  --reason      "<short description>" \
+  --alert-url   "<github issue or alert URL>"
+```
+
+## What it does
+
+1. Asserts no privileged credentials in environment (RELEASE_APP_PRIVATE_KEY,
+   KUBECONFIG, VAULT_TOKEN, ACTIONS_ID_TOKEN_REQUEST_TOKEN).
+2. Checks App key age ≤ 90 days from SECURITY.md (fails loudly if stale).
+3. Resolves the artifact digest for `prior-tag` from GHCR.
+4. Creates branch `rollback/<service>/<prior-tag>` from main HEAD.
+5. Updates `registry/<service>.yaml` — sets `spec.artifact.digest` to prior digest.
+6. Appends an INCIDENTS.md entry.
+7. Returns: `{ rollback_branch, rollback_pr (COMPARE URL), merged: false }`.
+
+## Boundary
+
+This skill NEVER:
+- Opens a PR (returns COMPARE URL only — human must open the PR).
+- Merges, approves, or queues a PR.
+- Holds RELEASE_APP_PRIVATE_KEY, kubeconfig, Vault token, or OIDC token.
+
+## Required permissions
+
+`GITHUB_TOKEN` with `contents:write` for homelab-deploy (scoped App token via
+owner-controlled path — not a personal access token).
+
+## Edge cases
+
+- Key age > 90d: fails with rotation instructions before any mutation.
+- `rollbackTargetRetention.acknowledged` not set: fails before branch creation.
+- Tag re-pushed: uses digest resolution (not tag timestamp) for the prior version.

manifest.yaml

@@ -53,9 +53,11 @@ renderer:
     - .agents/skills/council-supervise/SKILL.md
     - .agents/skills/council-triage/SKILL.md
     - .agents/skills/council/SKILL.md
+    - .agents/skills/deploy-status/SKILL.md
     - .agents/skills/fleet-change/SKILL.md
     - .agents/skills/kb-first/SKILL.md
     - .agents/skills/open-pr/SKILL.md
+    - .agents/skills/prepare-rollback/SKILL.md
     - .agents/skills/run-tests/SKILL.md
     - .agents/skills/speckit-analyze/SKILL.md
     - .agents/skills/speckit-checklist/SKILL.md
@@ -92,9 +94,11 @@ renderer:
     - .claude/skills/council-supervise/SKILL.md
     - .claude/skills/council-triage/SKILL.md
     - .claude/skills/council/SKILL.md
+    - .claude/skills/deploy-status/SKILL.md
     - .claude/skills/fleet-change/SKILL.md
     - .claude/skills/kb-first/SKILL.md
     - .claude/skills/open-pr/SKILL.md
+    - .claude/skills/prepare-rollback/SKILL.md
     - .claude/skills/run-tests/SKILL.md
     - .claude/skills/token-economy/SKILL.md
     - .codex/hooks.json
@@ -381,6 +385,15 @@ skills:
       source_path: installer/install.sh
       target_path: "${CLAUDE_HOME}/skills/council/SKILL.md"
       codex_target_path: "${CODEX_HOME}/skills/council/SKILL.md"
+  - name: deploy-status
+    supported_agents: [codex, claude]
+    targets:
+      - agent: codex
+        path: .agents/skills/deploy-status/SKILL.md
+        sha256: 9aed5f4be488481a29b7c39b0ebb27f9e6aa718cabb8d9396451914321c0afea
+      - agent: claude
+        path: .claude/skills/deploy-status/SKILL.md
+        sha256: 9aed5f4be488481a29b7c39b0ebb27f9e6aa718cabb8d9396451914321c0afea
   - name: fleet-change
     supported_agents: [codex, claude]
     targets:
@@ -412,6 +425,15 @@ skills:
       - agent: claude
         path: .claude/skills/open-pr/SKILL.md
         sha256: 7e978da6a0555e2f93e30f6de6ad7069c18fa35b003b503bcbe91f8c9ad8b9df
+  - name: prepare-rollback
+    supported_agents: [codex, claude]
+    targets:
+      - agent: codex
+        path: .agents/skills/prepare-rollback/SKILL.md
+        sha256: 1bd398fe592c58a0c09cba4a5cc806bdb3a5ee8dcd9ac062773ef6634245fa3a
+      - agent: claude
+        path: .claude/skills/prepare-rollback/SKILL.md
+        sha256: 1bd398fe592c58a0c09cba4a5cc806bdb3a5ee8dcd9ac062773ef6634245fa3a
   - name: run-tests
     supported_agents: [codex, claude]
     targets:

pyproject.toml

@@ -5,6 +5,7 @@ requires-python = ">=3.11"
 license = "LicenseRef-JorisJonkers-Proprietary-1.0"
 dependencies = [
   "PyYAML>=6.0,<7",
+  "requests>=2.32,<3",
 ]
 
 [dependency-groups]
@@ -18,6 +19,9 @@ dev = [
 [tool.uv]
 package = false
 
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
 [tool.setuptools]
 py-modules = []
 

templates/repo/.agents/skills/deploy-status/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: deploy-status
+description: Fetch and summarise the gate status for a homelab-deploy pull request. Reports each of the four required checks and whether the PR is merge-ready.
+---
+
+# deploy-status skill
+
+## Purpose
+
+Fetch and summarise the gate status for a homelab-deploy pull request.
+Reports each of the four required checks and whether the PR is merge-ready.
+
+## Usage
+
+```
+deploy-status --pr <number> [--repo homelab-deploy]
+```
+
+## What it does
+
+1. Resolves the PR head SHA.
+2. Lists check runs for that SHA.
+3. Downloads gate-summary artifacts (SC-4) from the associated Pipeline Complete run.
+4. Returns a structured summary:
+   - `gates[]` — one entry per required check: Compose Gate, Leak Scan,
+     Stack Integration Gate, Pipeline Complete.
+   - `merge_ready` — true only when Pipeline Complete is "pass" AND all gates pass.
+   - `blocker` — name of the first non-pass gate, or null.
+
+## Authoritative source
+
+`Pipeline Complete` is the authoritative merge-readiness signal.
+Do not infer merge-readiness from individual gate conclusions alone.
+
+## Limitations
+
+- Read-only. Never merges, approves, or enqueues.
+- Requires `GITHUB_TOKEN` env var with `contents:read` + `actions:read`.
+- Stale artifacts (force-pushed head): always uses latest-head-SHA artifacts.
+
+## Edge cases
+
+- Missing artifact: gate status shown as "pending" or "missing"; not an error.
+- Merge-queue vs PR-head drift: always uses PR head SHA, not merge_group SHA.
+- Tag re-pushed: latest artifact by created_at wins.

templates/repo/.agents/skills/prepare-rollback/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: prepare-rollback
+description: Prepare a rollback branch that pins one service to a prior artifact version. Returns a COMPARE URL for human review. NEVER merges or approves.
+---
+
+# prepare-rollback skill
+
+## Purpose
+
+Prepare a rollback branch that pins one service to a prior artifact version.
+Returns a COMPARE URL for human review. NEVER merges or approves.
+
+## Usage
+
+```
+prepare-rollback \
+  --service     <unit-name> \
+  --prior-tag   <semver-tag> \
+  --reason      "<short description>" \
+  --alert-url   "<github issue or alert URL>"
+```
+
+## What it does
+
+1. Asserts no privileged credentials in environment (RELEASE_APP_PRIVATE_KEY,
+   KUBECONFIG, VAULT_TOKEN, ACTIONS_ID_TOKEN_REQUEST_TOKEN).
+2. Checks App key age ≤ 90 days from SECURITY.md (fails loudly if stale).
+3. Resolves the artifact digest for `prior-tag` from GHCR.
+4. Creates branch `rollback/<service>/<prior-tag>` from main HEAD.
+5. Updates `registry/<service>.yaml` — sets `spec.artifact.digest` to prior digest.
+6. Appends an INCIDENTS.md entry.
+7. Returns: `{ rollback_branch, rollback_pr (COMPARE URL), merged: false }`.
+
+## Boundary
+
+This skill NEVER:
+- Opens a PR (returns COMPARE URL only — human must open the PR).
+- Merges, approves, or queues a PR.
+- Holds RELEASE_APP_PRIVATE_KEY, kubeconfig, Vault token, or OIDC token.
+
+## Required permissions
+
+`GITHUB_TOKEN` with `contents:write` for homelab-deploy (scoped App token via
+owner-controlled path — not a personal access token).
+
+## Edge cases
+
+- Key age > 90d: fails with rotation instructions before any mutation.
+- `rollbackTargetRetention.acknowledged` not set: fails before branch creation.
+- Tag re-pushed: uses digest resolution (not tag timestamp) for the prior version.