claude-dev-env 2.0.2 → 2.1.0

package/skills/pr-converge/reference/CLAUDE.md

@@ -6,6 +6,7 @@ Reference documents for the `pr-converge` skill. These files define the per-tick
 
 | File | Purpose |
 |---|---|
+| `progress-checklist.md` | The per-tick eleven-step checklist (Step 0 open → Step 11 report), each step pointing to its spoke file |
 | `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run the internal CODE_REVIEW and BUGTEAM phases, then the terminal BUGBOT and COPILOT_WAIT gates, schedule next wakeup) |
 | `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
 | `fix-protocol.md` | pr-converge deltas on the `pr-fix-protocol` skill: multi-PR teammate obligations and the same-tick bugbot re-trigger rule |

package/skills/pr-converge/reference/progress-checklist.md

@@ -0,0 +1,168 @@
+# pr-converge progress checklist
+
+The per-tick step sequence for the pr-converge loop. The hub
+([`../SKILL.md`](../SKILL.md)) points here; run these steps in order, one pass
+per tick.
+
+State variables (`phase`, `bugbot_clean_at`, `code_review_clean_at`,
+`bugteam_clean_at`, `copilot_clean_at`, `merge_state_status`, counters) are
+defined in [`state-schema.md`](state-schema.md). Ground rules
+in [`ground-rules.md`](ground-rules.md).
+
+Each step references its spoke file for full procedural detail — MCP calls,
+script invocations, decision criteria. Every "return to Step N" means the next
+tick starts fresh from that step.
+
+**Hard gate: do not advance from any step while ANY unresolved review
+thread exists on the PR.** Sweep semantics and per-thread handling live in
+the shared fix protocol
+([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md)
+step 12; skill deltas in [`fix-protocol.md`](fix-protocol.md)).
+
+**Full-PR-diff rule: every CODE-REVIEW round (Step 5) and every BUGTEAM
+round (Step 6) covers the FULL `origin/main...HEAD` diff — every file
+the PR touches.** A round that scopes to a subset — only the last commit,
+only files touched since the prior clean SHA, only bugbot-flagged paths,
+or any other delta cut — does not satisfy the gate, and a "clean" verdict
+against a partial diff is not a valid clean. Re-run the round against the
+full diff before recording `code_review_clean_at` or treating the bugteam
+round as converged. This rule holds every tick, every loop, every PR.
+
+- [ ] **Step 0: Open the run**
+      Apply the `pr-loop-lifecycle` skill's Open section
+      (`../../pr-loop-lifecycle/SKILL.md`): permission grant + worktree preflight.
+
+- [ ] **Step 1: Resolve PR scope + PR worktree**
+      Apply Step 1.5 scope resolution in
+      [`per-tick.md`](per-tick.md). Resolve the **PR
+      worktree** — the local checkout every local step this tick targets:
+      the `EnterWorktree` checkout when the PR shares the session's repo,
+      else a checkout of the PR's repo that the working directory routes
+      into via `cd`. Cross-repo routing is automatic, not a fork.
+      See: [`per-tick.md` § Step 1](per-tick.md)
+      and [§ Step 1.5](per-tick.md)
+
+- [ ] **Step 2: Initialize loop state**
+      `phase = CODE_REVIEW`; all counters at zero; `run_name` resolved.
+
+- [ ] **Step 3: Mergeability check**
+      See: [`convergence-gates.md` § (c)](convergence-gates.md)
+
+      ```
+      pull_request_read(method="get") → .mergeable_state, .mergeable
+      ```
+
+      - [ ] mergeable → advance to Step 4
+      - [ ] not mergeable → rebase → force-push → return to Step 1
+
+- [ ] **Step 4: BUGBOT — terminal Bugbot confirmation gate**
+      Step 6 routes here after BUGTEAM converges. Bugbot confirms code the
+      internal passes already drove to clean.
+      See: [`per-tick.md` § BUGBOT terminal gate + Step 3](per-tick.md);
+      availability and trigger via `reviewer-gates`
+      (`../../reviewer-gates/SKILL.md` § Gate 1 / Gate 3).
+
+      - [ ] **disabled / down** → `bugbot_down = true` → Step 7
+      - [ ] **dirty on `current_head`** → apply shared fix protocol
+            ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md);
+            skill deltas in [`fix-protocol.md`](fix-protocol.md))
+            → push → reset push-invalidated markers → `phase = CODE_REVIEW` → Step 5
+      - [ ] **clean on `current_head`** → zero unresolved threads (else fix + resolve first)
+            → `bugbot_clean_at = current_head` → Step 7
+      - [ ] **no review / commit_id mismatch** → `reviewer-gates` Bugbot flow (Gate 3):
+            silent pass → stamp + Step 7; queued/triggered → 360s wakeup → Step 4;
+            down → `bugbot_down = true` → Step 7
+
+- [ ] **Step 5: CODE-REVIEW — static sweep, review, fix, advance**
+      Entry phase every tick; re-entered after any fix push.
+      See: [`per-tick.md` § CODE_REVIEW entry](per-tick.md).
+      Pre-condition: cwd is the Step 1.5 PR worktree on `current_head`.
+      Scope: FULL `origin/main...HEAD` diff every tick (no path args, no delta cut).
+      Review always runs at effort high on model opus through
+      `invoke_code_review.py`. Mode decision inputs: host profile + session
+      model. Call:
+      `python "$HOME/.claude/scripts/invoke_code_review.py" --cwd <PR-worktree>
+      --session-model <alias>`. Chain mode uses that cwd and empty stdin; the
+      chain process never commits and never pushes. JSON stdout carries
+      `mode` (`in_session` | `chain`), `served_command`, `returncode`, and
+      `dirty_tree`. Config/host errors still emit that JSON with non-zero
+      `returncode` (no traceback-only failure).
+
+      - [ ] **Static sweep fails** → apply shared fix protocol → push → reset markers
+            → stay CODE_REVIEW → Step 5
+      - [ ] **`mode == in_session`** (Claude host, session model opus) → run
+            `/code-review high --fix` in-session (no path args)
+      - [ ] **`mode == chain`** (any other host or non-opus session) → helper
+            already ran the headless review; read `returncode`,
+            `served_command`, and `dirty_tree` from JSON
+      - [ ] **failed review** (`returncode != 0`, or chain with null
+            `served_command`) → do not set `code_review_clean_at` → stay
+            CODE_REVIEW → Step 5
+      - [ ] **fixes applied** (`dirty_tree` true / working tree dirty) →
+            commit + push via shared fix protocol → reset markers → stay
+            CODE_REVIEW → Step 5
+      - [ ] **clean** (successful serve: `returncode == 0`, chain
+            `served_command` non-null when chain, and `dirty_tree` false) →
+            zero unresolved threads (else fix + resolve) →
+            `code_review_clean_at = current_head` → `phase = BUGTEAM` → Step 6
+
+- [ ] **Step 6: BUGTEAM — run, decide, fix, reply, resolve**
+      See: [`per-tick.md` § Step 2 BUGTEAM](per-tick.md);
+      [`../../bugteam/SKILL.md`](../../bugteam/SKILL.md).
+      Pre-condition: `code_review_clean_at == current_head`.
+      Mandatory: `Skill({skill: "bugteam", args: "<PR URL>"})` this tick
+      (enforcer-blocked otherwise; `qbug` is not a substitute). Scope: FULL
+      `origin/main...HEAD` diff. Re-resolve HEAD after bugteam.
+
+      - [ ] **bugteam pushed** → verify threads replied + resolved → reset markers
+            → `phase = CODE_REVIEW` → 360s wakeup → Step 5
+      - [ ] **converged, no push** → zero unresolved threads →
+            `bugteam_clean_at = current_head` → `phase = BUGBOT` → Step 4
+      - [ ] **findings without committed fixes** → apply shared fix protocol → push →
+            reset markers → `phase = CODE_REVIEW` → Step 5
+
+- [ ] **Step 7: Convergence gates**
+      Full procedure: [`convergence-gates.md`](convergence-gates.md).
+
+      Pre-condition: Step 6 converged AND (`bugbot_clean_at == current_head` OR
+      `bugbot_down`). The terminal Bugbot gate (Step 4) sets that state just
+      before these gates run. Count unresolved threads before each gate.
+      Every gate records evidence; gate (f) cites evidence from (a)–(e).
+
+      - [ ] **(a) Copilot findings** — fetch Copilot on `current_head`; dirty → fix + return to Step 5; clean → stamp `copilot_clean_at`; absent → continue; when `copilot_down`, skip
+      - [ ] **(b) Claude reviewer** — fetch Claude on `current_head`; dirty → fix + return to Step 5; clean or absent → continue
+      - [ ] **(c) Mergeability** — `mergeable_state == "clean"` and `mergeable == true`; dirty → rebase + return to Step 1; blocked/behind/unknown/unstable → hard blocker
+      - [ ] **(d) Post-convergence Copilot request** — request Copilot when not pending and not `copilot_down`; enter `COPILOT_WAIT` (Step 7a); when `copilot_down`, skip to (e)
+      - [ ] **(e) Thread-resolution** — zero unresolved threads across the PR; else sweep + fix/resolve
+      - [ ] **(f) Mark ready** — run `check_convergence.py`; exit 0 → `update_pull_request(draft=false)` → Step 8; exit 1 → fix path; exit 2 → retry/stop
+
+- [ ] **Step 7a: COPILOT_WAIT — fetch Copilot, decide**
+      See: [`per-tick.md` § Step 2 COPILOT_WAIT](per-tick.md).
+      Skipped entirely when `copilot_down` (gate (d) never enters this phase).
+
+      - [ ] **clean** → `copilot_clean_at = current_head` → Step 7 (re-validate (b), (c), (e), (f))
+      - [ ] **dirty** → apply shared fix protocol
+            ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md);
+            skill deltas in [`fix-protocol.md`](fix-protocol.md))
+            → push → reset markers → `phase = CODE_REVIEW` → Step 5
+      - [ ] **no review yet** → increment `copilot_wait_count` → ≥ 3 hard-blocks;
+            else 360s wakeup → Step 7a next tick
+
+- [ ] **Step 8: Clean working tree**
+      `pr-loop-lifecycle` Close (`../../pr-loop-lifecycle/SKILL.md`).
+      See: [`../../pr-loop-lifecycle/reference/teardown-publish-permissions.md` § Clean working tree](../../pr-loop-lifecycle/reference/teardown-publish-permissions.md)
+
+- [ ] **Step 9: Rewrite PR description**
+      `pr-loop-lifecycle` Close.
+      See: [`../../pr-loop-lifecycle/reference/teardown-publish-permissions.md` § Publish the final PR description](../../pr-loop-lifecycle/reference/teardown-publish-permissions.md)
+
+- [ ] **Step 10: Revoke project permissions (always)**
+      `pr-loop-lifecycle` Close (`../../pr-loop-lifecycle/SKILL.md` § Close).
+
+- [ ] **Step 11: Print final report**
+      Print this block verbatim — no paraphrase, no extra commentary:
+      ```
+      /pr-converge exit: converged
+      Loops: <N>
+      Final commit: <SHA>
+      ```

package/skills/pr-converge/test_step5_host_branch.py

@@ -11,7 +11,7 @@ from pathlib import Path
 
 
 SKILL_ROOT = Path(__file__).resolve().parent
-SKILL_MARKDOWN_PATH = SKILL_ROOT / "SKILL.md"
+PROGRESS_CHECKLIST_MARKDOWN_PATH = SKILL_ROOT / "reference" / "progress-checklist.md"
 PER_TICK_MARKDOWN_PATH = SKILL_ROOT / "reference" / "per-tick.md"
 
 HELPER_SCRIPT_NAME = "invoke_code_review.py"
@@ -45,10 +45,10 @@ def _code_review_section(per_tick_text: str) -> str:
     return per_tick_text[section_start:section_end]
 
 
-def _step_five_checklist(skill_text: str) -> str:
-    step_start = skill_text.index("**Step 5: CODE-REVIEW")
-    step_end = skill_text.index("**Step 6: BUGTEAM", step_start)
-    return skill_text[step_start:step_end]
+def _step_five_checklist(progress_checklist_text: str) -> str:
+    step_start = progress_checklist_text.index("**Step 5: CODE-REVIEW")
+    step_end = progress_checklist_text.index("**Step 6: BUGTEAM", step_start)
+    return progress_checklist_text[step_start:step_end]
 
 
 def test_per_tick_code_review_names_helper_and_mode_inputs() -> None:
@@ -75,7 +75,9 @@ def test_per_tick_code_review_names_helper_and_mode_inputs() -> None:
 
 
 def test_skill_step_five_checklist_names_helper_and_mode_inputs() -> None:
-    step_five_checklist = _step_five_checklist(_read_markdown(SKILL_MARKDOWN_PATH))
+    step_five_checklist = _step_five_checklist(
+        _read_markdown(PROGRESS_CHECKLIST_MARKDOWN_PATH)
+    )
     assert HELPER_SCRIPT_NAME in step_five_checklist
     assert HOST_PROFILE_PHRASE in step_five_checklist
     assert SESSION_MODEL_PHRASE in step_five_checklist

package/skills/pr-loop-cloud-transport/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-loop-cloud-transport
-description: Runs any PR-loop skill in a Claude Code session whose gh CLI cannot act on the PR — the binary is absent, gh auth status fails, or the active login cannot act on the PR's owner. A six-step transport workflow loads the GitHub MCP schemas, fixes origin/HEAD before pushes, keys review rules to the live MCP identity, routes every GitHub operation through the gh-to-MCP substitution matrix, reads Copilot status from what lands on the PR, and self-checks the posts the gh-text hooks cannot gate. Use at run start when pr-converge, autoconverge, bugteam, qbug, findbugs, fixbugs, monitor-open-prs, or copilot-review runs in a cloud session, when `command -v gh` or `gh auth status` fails, or when an MCP tool call fails with InputValidationError.
+description: Runs any PR-loop skill in a Claude Code session whose gh CLI cannot act on the PR. Use at run start when pr-converge, autoconverge, bugteam, qbug, findbugs, fixbugs, monitor-open-prs, or copilot-review runs in a cloud session, when `command -v gh` or `gh auth status` fails, or when an MCP tool call fails with InputValidationError.
 ---
 
 # PR-loop cloud transport

package/skills/privacy-hygiene/SKILL.md

@@ -1,115 +1,68 @@
----
-name: privacy-hygiene
-description: Full-repo sweep for personal data and secrets before commit or durable GitHub post. Use when preparing a PR, cleaning a leak, or when `pii_prevention_blocker` denies a write, post, or commit. Triggers on "privacy hygiene", "personal data", "secret sweep", "sanitize repository", "/privacy-hygiene".
----
-
-# privacy-hygiene
-
-## Overview
-
-Find and remove personal data and high-confidence secrets before they land in git history or a durable GitHub post. The `pii_prevention_blocker` hook blocks the common cases at write, post, and commit time. This skill is the full sweep when you need a broader pass or a remediation plan.
-
-**Announce at start:** "Running privacy-hygiene sweep."
-
-## When to run a full sweep
-
-- Before the first push of a branch that touched logs, screenshots, config samples, or machine-local paths
-- After a hook block on email, home path, LAN address, or secret material
-- Before opening a PR to a repository that is public (or will be made public)
-- After pasting support tickets, env dumps, or terminal transcripts into the tree
-
-## What the automated gate blocks
-
-| Category | Blocked examples | Allowed residual |
-|---|---|---|
-| Email | `user@example.com` | `user@example.com`, `user@example.org`, `user@example.net` |
-| Home path | `C:/Users/example/...`, `/Users/example/...`, `/home/example/...` | `C:/Users/example/...`, `C:/Users/<you>/...`, `/Users/alice/...` |
-| LAN address | Unlisted `10.x` / `172.16–31.x` / `192.168.x` | Public addresses; your NAS host from `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`; entries in `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` |
-| Secret | `ghp_…`, `github_pat_…`, `AKIA…`, PEM private-key headers | Public keys, redacted `***`, env var names without values |
-
-Surfaces:
-
-1. **Write / Edit / MultiEdit** — payload text about to land on disk (via PreToolUse dispatcher)
-2. **Durable posts** — `gh pr/issue create|comment|edit|review` bodies and GitHub MCP body/comment fields (Bash and PowerShell)
-3. **git commit** — staged blob text (non-exempt paths) on Bash and PowerShell, including `git.exe` and flag forms (`--no-verify`, `-c`, `-C`). Commit message bodies (`-m` / `-F`) are out of scope for the automated gate
-
-## Sweep procedure
-
-### 1. Scope the tree
-
-```
-git status -sb
-git diff --stat
-git diff --cached --stat
-```
-
-Prefer the branch diff vs `origin/main` for PR prep:
-
-```
-git fetch origin main
-git diff --name-only origin/main...HEAD
-```
-
-### 2. Search for high-confidence patterns
-
-Run from the repo root (PowerShell-friendly example):
-
-```
-rg -n --hidden -g '!node_modules' -g '!.git' -e '@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' -e 'Users[/\\][^/\\]+' -e '[/]home/[^/]+' -e '\b(10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[0-1])\.\d+\.\d+)\b' -e '\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b' -e '\bgithub_pat_[A-Za-z0-9_]{20,}\b' -e '\bAKIA[0-9A-Z]{16}\b' -e '-----BEGIN [A-Z ]*PRIVATE KEY-----'
-```
-
-Review each hit. Ignore:
-
-- Test fixtures under `test_*.py` / `*_test.py` / `/tests/` (synthetic only)
-- `LICENSE` / copyright notice identity that is intentional and public
-- This package's own `pii_scanner` / `pii_prevention_constants` modules
-- Documented placeholders (`user@example.com`, `C:/Users/<you>/`)
-
-### 3. Remediate
-
-| Hit | Fix |
-|---|---|
-| Real email | Replace with `user@example.com` or remove |
-| Home path | Use `Path.home()`, `~`, or `C:/Users/<you>/` |
-| LAN address | Remove, use a hostname, or — for your own NAS — set the host in `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`, both of which stay out of git |
-| Credential material | Remove from the tree; rotate the credential; load from env/secret store |
-| Already committed | Rewrite is not enough if already pushed — rotate secrets; scrub history only with explicit user approval |
-
-### 4. Re-check before commit / post
-
-- Stage only clean files
-- Prefer `--body-file` for `gh` posts (also required by the gh-body-file rule)
-- Let `pii_prevention_blocker` re-run on the next Write / commit / post
-
-## Accepted residual (do not over-scrub)
-
-- LICENSE copyright lines naming a legal person or org that owns the work
-- Intentional public maintainer identity published on purpose
-- Example domains reserved for documentation (`example.com` and siblings)
-- Placeholder home users (`example`, `user`, `alice`, `<you>`, `YOUR_USER`)
-- The NAS host you configure locally (allowlisted at scan time, never committed)
-- Public addresses and docs that name private ranges without a live host (still prefer hostnames)
-
-## Enable on any machine / public repository
-
-Install or reinstall the package so hooks and this skill land under `~/.claude/`:
-
-```
-cd packages/claude-dev-env
-node bin/install.mjs
-```
-
-Hooks register via `hooks/hooks.json` into `~/.claude/settings.json`. Once installed, the same gates apply in every repository the agent touches — private or public.
-
-## Open knobs
-
-- **NAS / LAN allowlist:** Unlisted private IPs are blocked. The scanner resolves your NAS host from `CLAUDE_NAS_HOST`, then `~/.claude/local-identity.json` (`nas.host`), and allowlists it when it is a private address, so the committed tree holds no real host. `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` in `hooks_constants` holds the static allowlist for any host every machine must share.
-- **Commit-scan exempt repositories:** named owner/repo slugs skip the staged-commit PII scan only. Set `CLAUDE_PII_EXEMPT_REPOS` (comma-separated `owner/repo` values) or list them under `pii_exempt_repositories` in `~/.claude/local-identity.json`. Matching uses the repository's `remote.origin.url` and accepts only the exact host `github.com` (https, ssh scheme, or scp-style). A repository with no readable origin is never exempt (fail-closed to scanning). Write / Edit / MultiEdit and durable post bodies still scan in every repository.
-- **Public maintainer identity:** when a real email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
-
-## What this skill does not do
-
-- Does not rewrite git history without explicit user approval
-- Does not rotate credentials for you
-- Does not replace the write-time hook — it complements it
-- Does not scan commit-message text (`-m` / `-F`); keep messages free of secrets yourself
+---
+name: privacy-hygiene
+description: Full-repo sweep for personal data and secrets before commit or durable GitHub post. Use when preparing a PR, cleaning a leak, or when `pii_prevention_blocker` denies a write, post, or commit. Triggers on "privacy hygiene", "personal data", "secret sweep", "sanitize repository", "/privacy-hygiene".
+---
+
+# privacy-hygiene
+
+## Overview
+
+Find and remove personal data and high-confidence secrets before they land in git history or a durable GitHub post. The `pii_prevention_blocker` hook blocks the common cases at write, post, and commit time. This skill is the full sweep when you need a broader pass or a remediation plan.
+
+**Announce at start:** "Running privacy-hygiene sweep."
+
+## When to run a full sweep
+
+- Before the first push of a branch that touched logs, screenshots, config samples, or machine-local paths
+- After a hook block on email, home path, LAN address, or secret material
+- Before opening a PR to a repository that is public (or will be made public)
+- After pasting support tickets, env dumps, or terminal transcripts into the tree
+
+## What the automated gate blocks
+
+| Category | Blocked examples | Allowed residual |
+|---|---|---|
+| Email | `user@example.com` | `user@example.com`, `user@example.org`, `user@example.net` |
+| Home path | `C:/Users/example/...`, `/Users/example/...`, `/home/example/...` | `C:/Users/example/...`, `C:/Users/<you>/...`, `/Users/alice/...` |
+| LAN address | Unlisted `10.x` / `172.16–31.x` / `192.168.x` | Public addresses; your NAS host from `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`; entries in `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` |
+| Secret | `ghp_…`, `github_pat_…`, `AKIA…`, PEM private-key headers | Public keys, redacted `***`, env var names without values |
+
+Surfaces:
+
+1. **Write / Edit / MultiEdit** — payload text about to land on disk (via PreToolUse dispatcher)
+2. **Durable posts** — `gh pr/issue create|comment|edit|review` bodies and GitHub MCP body/comment fields (Bash and PowerShell)
+3. **git commit** — staged blob text (non-exempt paths) on Bash and PowerShell, including `git.exe` and flag forms (`--no-verify`, `-c`, `-C`). Commit message bodies (`-m` / `-F`) are out of scope for the automated gate
+
+## Sweep procedure
+
+Run the full-tree sweep in
+[`reference/sweep-procedure.md`](reference/sweep-procedure.md): scope the tree,
+run the ripgrep pass for the four high-confidence pattern families (email, home
+path, LAN address, secret), review each hit against the ignore list, and
+remediate. It also lists the accepted residual — what to leave in place rather
+than over-scrub. The ripgrep command is the only full-tree pass; the write-time
+`pii_prevention_blocker` scans one payload at a time.
+
+## Enable on any machine / public repository
+
+Install or reinstall the package so hooks and this skill land under `~/.claude/`:
+
+```
+cd packages/claude-dev-env
+node bin/install.mjs
+```
+
+Hooks register via `hooks/hooks.json` into `~/.claude/settings.json`. Once installed, the same gates apply in every repository the agent touches — private or public.
+
+## Open knobs
+
+- **NAS / LAN allowlist:** Unlisted private IPs are blocked. The scanner resolves your NAS host from `CLAUDE_NAS_HOST`, then `~/.claude/local-identity.json` (`nas.host`), and allowlists it when it is a private address, so the committed tree holds no real host. `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` in `hooks_constants` holds the static allowlist for any host every machine must share.
+- **Commit-scan exempt repositories:** named owner/repo slugs skip the staged-commit PII scan only. Set `CLAUDE_PII_EXEMPT_REPOS` (comma-separated `owner/repo` values) or list them under `pii_exempt_repositories` in `~/.claude/local-identity.json`. Matching uses the repository's `remote.origin.url` and accepts only the exact host `github.com` (https, ssh scheme, or scp-style). A repository with no readable origin is never exempt (fail-closed to scanning). Write / Edit / MultiEdit and durable post bodies still scan in every repository.
+- **Public maintainer identity:** when a real email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
+
+## What this skill does not do
+
+- Does not rewrite git history without explicit user approval
+- Does not rotate credentials for you
+- Does not replace the write-time hook — it complements it
+- Does not scan commit-message text (`-m` / `-F`); keep messages free of secrets yourself

package/skills/privacy-hygiene/reference/sweep-procedure.md

@@ -0,0 +1,62 @@
+# Full-tree PII sweep procedure
+
+The on-demand full-repository sweep for the `privacy-hygiene` skill — the
+complement to the write-time `pii_prevention_blocker`, which scans one payload at
+a time. The canonical per-payload patterns live in the hooks' `pii_scanner` and
+`pii_prevention_constants` modules; the ripgrep command below is the only
+full-tree pass. The hub ([`../SKILL.md`](../SKILL.md)) points here.
+
+## 1. Scope the tree
+
+```
+git status -sb
+git diff --stat
+git diff --cached --stat
+```
+
+Prefer the branch diff vs `origin/main` for PR prep:
+
+```
+git fetch origin main
+git diff --name-only origin/main...HEAD
+```
+
+## 2. Search for high-confidence patterns
+
+Run from the repo root (PowerShell-friendly example):
+
+```
+rg -n --hidden -g '!node_modules' -g '!.git' -e '@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' -e 'Users[/\\][^/\\]+' -e '[/]home/[^/]+' -e '\b(10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[0-1])\.\d+\.\d+)\b' -e '\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b' -e '\bgithub_pat_[A-Za-z0-9_]{20,}\b' -e '\bAKIA[0-9A-Z]{16}\b' -e '-----BEGIN [A-Z ]*PRIVATE KEY-----'
+```
+
+Review each hit. Ignore:
+
+- Test fixtures under `test_*.py` / `*_test.py` / `/tests/` (synthetic only)
+- `LICENSE` / copyright notice identity that is intentional and public
+- This package's own `pii_scanner` / `pii_prevention_constants` modules
+- Documented placeholders (`user@example.com`, `C:/Users/<you>/`)
+
+## 3. Remediate
+
+| Hit | Fix |
+|---|---|
+| Real email | Replace with `user@example.com` or remove |
+| Home path | Use `Path.home()`, `~`, or `C:/Users/<you>/` |
+| LAN address | Remove, use a hostname, or — for your own NAS — set the host in `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`, both of which stay out of git |
+| Credential material | Remove from the tree; rotate the credential; load from env/secret store |
+| Already committed | Rewrite is not enough if already pushed — rotate secrets; scrub history only with explicit user approval |
+
+## 4. Re-check before commit / post
+
+- Stage only clean files
+- Prefer `--body-file` for `gh` posts (also required by the gh-body-file rule)
+- Let `pii_prevention_blocker` re-run on the next Write / commit / post
+
+## Accepted residual (do not over-scrub)
+
+- LICENSE copyright lines naming a legal person or org that owns the work
+- Intentional public maintainer identity published on purpose
+- Example domains reserved for documentation (`example.com` and siblings)
+- Placeholder home users (`example`, `user`, `alice`, `<you>`, `YOUR_USER`)
+- The NAS host you configure locally (allowlisted at scan time, never committed)
+- Public addresses and docs that name private ranges without a live host (still prefer hostnames)

package/skills/session-log/CLAUDE.md

@@ -12,7 +12,8 @@ Produces a self-contained HTML session report shaped to the session's character
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Hub — six steps, gotchas, backend detection, frontmatter contract, run-and-report checklist. Single-file skill; no companion files. |
+| `SKILL.md` | Hub — six steps, gotchas, backend detection, run-and-report checklist. |
+| `templates/frontmatter.md` | The session-page frontmatter contract and the Step 3 notes block. |
 
 ## Six steps
 

package/skills/session-log/SKILL.md

@@ -60,21 +60,7 @@ Resolve the metadata used by the frontmatter and the vault path:
 - **Date:** today's date
 - **Title:** a 2–5 word summary of the session's primary outcome. Examples: "Amazon Auth Migration", "Source Loading Fix", "PR 475 Convergence". Avoid generic titles like "Bug Fixes".
 
-The frontmatter contract every session report carries (inside an HTML comment, as the first child of `<body>`):
-
-```html
-<!--
-type: session-report
-project: [name]
-session: [N]
-session_id: [uuid]
-date: [YYYY-MM-DD]
-status: completed|in-progress|blocked
-blocked: true|false
-vault_context_retrieved: true|false
-tags: [session, [project-tag], [topic-tags]]
--->
-```
+The frontmatter contract every session report carries (inside an HTML comment, as the first child of `<body>`) is the metadata block in [`templates/frontmatter.md`](templates/frontmatter.md).
 
 Every session report carries this metadata block verbatim so vault search and the tidy step in step 5 work. **Initial values for Step 2's Write:** substitute concrete values for every placeholder — for `session_id`, write the value read from `CLAUDE_CODE_SESSION_ID` in step 1 (or `unknown` when the variable is unset); for `vault_context_retrieved`, write the literal value `false` (the safe default before Step 3's vault-MCP-tool scan completes). Step 3 then Edits `vault_context_retrieved` to `true` if any of the three vault MCP tools fired this session.
 
@@ -113,16 +99,7 @@ Review the conversation history for any use of these vault MCP tools (look only
 Edit the vault HTML via two Edit calls:
 
 1. Set the frontmatter `vault_context_retrieved` field to `true` when any of the three tools fired this session, `false` otherwise.
-2. Append one fact — vault-context status — into whatever section the report designer placed for notes / metadata / references. If the report has no such section, append a fresh `<h2>Notes</h2>` block at the end of the content:
-
-```html
-<h2>Notes</h2>
-<ul>
-  <!-- Pick exactly one of the two forms based on whether vault MCP tools fired this session: -->
-  <li><strong>Vault context:</strong> Retrieved ([list of note paths])</li>
-  <li><strong>Vault context:</strong> Not retrieved</li>
-</ul>
-```
+2. Append one fact — vault-context status — into whatever section the report designer placed for notes / metadata / references. If the report has no such section, append a fresh `<h2>Notes</h2>` block (in [`templates/frontmatter.md`](templates/frontmatter.md)) at the end of the content.
 
 If the report already has a notes / references section, use Edit to insert one matching child element at the end of that section. The element shape mirrors whatever the section already uses: an extra `<li>` before the closing `</ul>` for a list, an extra `<dt>Vault context</dt><dd>…</dd>` pair before the closing `</dl>` for a description list, an extra `<p><strong>Vault context:</strong> …</p>` before the section's closing tag for a paragraph-based section. Pick the form that matches the surrounding markup.
 
@@ -189,4 +166,5 @@ The primary outcome comes from the session title resolved in step 1.
 
 ## Folder map
 
-- `SKILL.md` — this hub. Single-file skill; no companions.
+- `SKILL.md` — this hub.
+- `templates/frontmatter.md` — the report frontmatter contract and the Step 3 notes block.

package/skills/session-log/templates/frontmatter.md

@@ -0,0 +1,40 @@
+# Session-log template blocks
+
+The two verbatim HTML blocks the `session-log` skill drops into every session
+page. The hub ([`../SKILL.md`](../SKILL.md)) points here from Step 1 / Step 2
+(frontmatter) and Step 3 (notes).
+
+## Frontmatter contract
+
+The first child of `<body>`, inside an HTML comment. Substitute a concrete value
+for every placeholder; `vault_context_retrieved` starts `false` and Step 3 sets
+it.
+
+```html
+<!--
+type: session-report
+project: [name]
+session: [N]
+session_id: [uuid]
+date: [YYYY-MM-DD]
+status: completed|in-progress|blocked
+blocked: true|false
+vault_context_retrieved: true|false
+tags: [session, [project-tag], [topic-tags]]
+-->
+```
+
+## Notes block (Step 3)
+
+Append one vault-context line. When the page already carries a notes /
+references section, add a matching child element to that section; use the block
+below only when the page has no such section.
+
+```html
+<h2>Notes</h2>
+<ul>
+  <!-- Pick exactly one of the two forms based on whether vault MCP tools fired this session: -->
+  <li><strong>Vault context:</strong> Retrieved ([list of note paths])</li>
+  <li><strong>Vault context:</strong> Not retrieved</li>
+</ul>
+```

package/skills/skill-builder/CLAUDE.md

@@ -1,12 +1,12 @@
 # skill-builder
 
-Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via `skill-writer`, enforce modularity (sub-skills / composition), write description as a trigger catalog, self-audit, and refine from real usage.
+Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via `skill-writer`, enforce modularity (sub-skills / composition), write description as a trigger catalog, require deterministic steps as code, self-audit, and refine from real usage.
 
-**Trigger:** build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, description trigger catalog.
+**Trigger:** build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, description trigger catalog, deterministic skill scripts.
 
 ## Purpose
 
-Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context (including composition plan and description triggers), delegates writing, and self-audits.
+Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context (composition plan, description triggers, deterministic inventory), delegates writing, and self-audits.
 
 ## Key files
 
@@ -17,13 +17,14 @@ Enforces craft standards for new and existing skills. For quick one-off SKILL.md
 | `references/progressive-disclosure.md` | Hub pattern, folder conventions, hard rules |
 | `references/skill-modularity.md` | Cross-skill modularity, sub-skills, composition plan |
 | `references/description-field.md` | Description as trigger catalog (not story prose) |
-| `references/self-audit-checklist.md` | Mandatory post-build audit |
+| `references/deterministic-elements.md` | Deterministic steps as code/task seeds; no markdown checkbox boards |
+| `references/self-audit-checklist.md` | Post-build audit task seeds (TaskCreate / TodoWrite) |
 | `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
 | `references/thariq-x-post-skills.json` | Source reference — lessons from building Claude Code skills |
 | `workflows/new-skill.md` | Full lifecycle for new skills (6 steps) |
 | `workflows/improve-skill.md` | Observation-first flow for existing skills (6 steps) |
 | `workflows/polish-skill.md` | Description trigger-catalog audit and final validation (5 steps) |
-| `templates/gap-analysis.md` | Gaps, composition plan, description triggers |
+| `templates/gap-analysis.md` | Gaps, composition plan, description triggers, deterministic inventory |
 
 ## Subdirectories
 
@@ -43,6 +44,6 @@ Enforces craft standards for new and existing skills. For quick one-off SKILL.md
 ## Conventions
 
 - Every build ends with the self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
-- Modularity items and description trigger-catalog items are mandatory on every delivery.
-- `skill-builder` orchestrates; `skill-writer` authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, degree-of-freedom assessment, and constraints.
+- Modularity items, description trigger-catalog items, and deterministic-element classification are mandatory on every delivery.
+- `skill-builder` orchestrates; `skill-writer` authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, deterministic inventory, degree-of-freedom assessment, and constraints.
 - Claude A / Claude B: Claude A (this session) designs; Claude B (subagents) tests the built skill on real tasks.