claude-dev-env 2.3.0 → 2.5.0

package/skills/pr-converge/scripts/test_check_convergence_gates.py

@@ -1,84 +1,84 @@
-"""Behavioral tests for the review and Bugbot convergence gate leaves.
-
-::
-
-    _flatten_paginated_reviews(two pages) -> newest-first flat list
-    _bugbot_run_conclusion_detail(success) -> (True, "check run ...")
-    _check_bugbot(named complete run) -> (True, "check run ...")
-
-Each test drives the real leaf, stubbing only the ``gh`` transport helpers.
-"""
-
-from __future__ import annotations
-
-import json
-
-import pytest
-
-import check_convergence_gates as gates
-
-
-def test_flatten_paginated_reviews_flattens_and_sorts_newest_first() -> None:
-    pages = [
-        [{"id": 1, "submitted_at": "2026-01-01T00:00:00Z"}],
-        [{"id": 2, "submitted_at": "2026-03-01T00:00:00Z"}],
-    ]
-    flattened = gates._flatten_paginated_reviews(json.dumps(pages))
-    assert flattened is not None
-    assert [each_review["id"] for each_review in flattened] == [2, 1]
-
-
-def test_flatten_paginated_reviews_returns_none_for_non_list_payload() -> None:
-    assert (
-        gates._flatten_paginated_reviews(json.dumps({"message": "Not Found"})) is None
-    )
-
-
-def test_bugbot_run_conclusion_detail_passes_on_a_complete_conclusion() -> None:
-    complete_conclusion = gates.ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS[0]
-    passed, detail = gates._bugbot_run_conclusion_detail(
-        {"id": 55, "conclusion": complete_conclusion, "html_url": ""}
-    )
-    assert passed is True
-    assert "check run 55" in detail
-
-
-def test_check_bugbot_reports_success_when_the_named_run_is_complete(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    complete_conclusion = gates.ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS[0]
-    run_name = f"x {gates.BUGBOT_CHECK_RUN_NAME_SUBSTRING} y"
-    payload = {
-        "check_runs": [
-            {
-                "name": run_name,
-                "id": 9,
-                "conclusion": complete_conclusion,
-                "html_url": "",
-            }
-        ]
-    }
-
-    def _stub_gh_api(endpoint_path: str) -> tuple[int, str]:
-        return 0, json.dumps(payload)
-
-    monkeypatch.setattr(gates, "_gh_api", _stub_gh_api)
-    passed, detail = gates._check_bugbot(owner="o", repo="r", sha="abc")
-    assert passed is True
-    assert "check run 9" in detail
-
-
-def should_evaluate_mergeable_from_pr_object_clean() -> None:
-    passed, detail = gates._evaluate_mergeable_from_pr_object(
-        {"mergeable": True, "mergeable_state": "clean"}
-    )
-    assert passed is True
-    assert detail == "clean"
-
-
-def should_evaluate_mergeable_from_pr_object_unknown() -> None:
-    passed, detail = gates._evaluate_mergeable_from_pr_object(
-        {"mergeable": None, "mergeable_state": "unknown"}
-    )
-    assert passed is False
-    assert detail == "unknown"
+"""Behavioral tests for the review and Bugbot convergence gate leaves.
+
+::
+
+    _flatten_paginated_reviews(two pages) -> newest-first flat list
+    _bugbot_run_conclusion_detail(success) -> (True, "check run ...")
+    _check_bugbot(named complete run) -> (True, "check run ...")
+
+Each test drives the real leaf, stubbing only the ``gh`` transport helpers.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+import check_convergence_gates as gates
+
+
+def test_flatten_paginated_reviews_flattens_and_sorts_newest_first() -> None:
+    pages = [
+        [{"id": 1, "submitted_at": "2026-01-01T00:00:00Z"}],
+        [{"id": 2, "submitted_at": "2026-03-01T00:00:00Z"}],
+    ]
+    flattened = gates._flatten_paginated_reviews(json.dumps(pages))
+    assert flattened is not None
+    assert [each_review["id"] for each_review in flattened] == [2, 1]
+
+
+def test_flatten_paginated_reviews_returns_none_for_non_list_payload() -> None:
+    assert (
+        gates._flatten_paginated_reviews(json.dumps({"message": "Not Found"})) is None
+    )
+
+
+def test_bugbot_run_conclusion_detail_passes_on_a_complete_conclusion() -> None:
+    complete_conclusion = gates.ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS[0]
+    passed, detail = gates._bugbot_run_conclusion_detail(
+        {"id": 55, "conclusion": complete_conclusion, "html_url": ""}
+    )
+    assert passed is True
+    assert "check run 55" in detail
+
+
+def test_check_bugbot_reports_success_when_the_named_run_is_complete(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    complete_conclusion = gates.ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS[0]
+    run_name = f"x {gates.BUGBOT_CHECK_RUN_NAME_SUBSTRING} y"
+    payload = {
+        "check_runs": [
+            {
+                "name": run_name,
+                "id": 9,
+                "conclusion": complete_conclusion,
+                "html_url": "",
+            }
+        ]
+    }
+
+    def _stub_gh_api(endpoint_path: str) -> tuple[int, str]:
+        return 0, json.dumps(payload)
+
+    monkeypatch.setattr(gates, "_gh_api", _stub_gh_api)
+    passed, detail = gates._check_bugbot(owner="o", repo="r", sha="abc")
+    assert passed is True
+    assert "check run 9" in detail
+
+
+def should_evaluate_mergeable_from_pr_object_clean() -> None:
+    passed, detail = gates._evaluate_mergeable_from_pr_object(
+        {"mergeable": True, "mergeable_state": "clean"}
+    )
+    assert passed is True
+    assert detail == "clean"
+
+
+def should_evaluate_mergeable_from_pr_object_unknown() -> None:
+    passed, detail = gates._evaluate_mergeable_from_pr_object(
+        {"mergeable": None, "mergeable_state": "unknown"}
+    )
+    assert passed is False
+    assert detail == "unknown"

package/skills/pr-converge/test_step5_host_branch.py

@@ -32,7 +32,7 @@ NEVER_PUSHES_PHRASE = "never pushes"
 EMPTY_STDIN_PHRASE = "empty"
 CWD_FLAG = "--cwd"
 OPUS_MODEL = "opus"
-HIGH_EFFORT_SLASH = "/code-review xhigh --fix"
+HIGH_EFFORT_SLASH = "/code-review ultra --fix"
 
 
 def _read_markdown(markdown_path: Path) -> str:

package/skills/pr-fix-protocol/SKILL.md

@@ -20,7 +20,7 @@ The caller passes: its identity, the PR scope, the PR worktree path, this round'
 
 ## Executor choice
 
-- **Single-PR loops** (no shared `state.json`): the lead spawns `Agent(subagent_type: "clean-coder")` to write the fix. Stop when `Agent` is unavailable. A spawned clean-coder starts in its own working directory, so its prompt names the PR worktree path and directs it to edit, stage, and commit there.
+- **Single-PR loops** (no shared `state.json`): the lead spawns `Agent(subagent_type: "clean-coder", model: "sonnet")` — worker-model routing per [`skills/orchestrator/SKILL.md`](../orchestrator/SKILL.md#workflow-agent-routing); resolver-supplied sonnet-equivalent on third-party hosts — to write the fix. Stop when `Agent` is unavailable. A spawned clean-coder starts in its own working directory, so its prompt names the PR worktree path and directs it to edit, stage, and commit there.
 - **Multi-PR orchestration** (shared `state.json`): a per-PR clean-coder teammate owns edits, replies, and state writes; the orchestrator holds back from inline edits. The teammate obligations — reply before writing state, which state fields to set, idle handoff — live in the calling skill's multi-PR reference.
 
 Run every git command in the PR worktree. `git add`, `git commit`, and `git push` act on the repo of the current working directory, so a cross-repo PR's fix lands in the PR's repo only when the working directory is its worktree.

package/skills/privacy-hygiene/SKILL.md

@@ -1,68 +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
-
-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
+---
+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/prototype/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: prototype
+description: >-
+  Isolated hookless worktree sandbox for zero-friction proof-of-concept builds, then a clean-room re-verification that promotes a successful POC into a real deploy. Triggers: prototype, /prototype, proof of concept, POC, spike, throwaway build, build without hooks, sandbox this idea, hookless worktree, prototype then ship, promote the prototype.
+---
+
+# Prototype
+
+## Principle
+
+Give a build the freedom to move fast, then make it earn the right to ship. Two phases, one hard wall between them:
+
+- **Sandbox** — an isolated worktree where an agent runs under `claude --bare`, so none of the standards gates (TDD, code rules, verified-commit, plain-language, stage) fire. The agent builds a proof-of-concept with zero friction.
+- **Promotion** — back in the normal, fully-hooked session, the successful POC goes through a clean-room re-verification before it becomes a commit and a pull request. Nothing from the sandbox rides along un-checked.
+
+Two safety gates stay live even in the sandbox: personal-data blocking and destructive-command blocking. A worktree shares the real repo's `.git` store and `rm` reaches the whole disk, so these are containment, not the "delays" the sandbox is meant to shed.
+
+## Gotchas
+
+Highest-signal content. Append a bullet each time a run fails in a new way.
+
+- A `--settings` file's hooks still load under `--bare` (the file is passed explicitly). That is the mechanism for keeping the two safety gates, not a bug.
+- The two safety hooks must point at the real installed scripts and import their `*_constants` packages at runtime. `scripts/build_sandbox_settings.py` resolves each hook's command from the live `~/.claude/settings.json` and registers it on the matchers the sandbox needs — personal-data on Write, Edit, MultiEdit, and Bash; destructive-command on Bash — so the paths stay correct on any machine and both gates cover the write surface. Do not hand-write the hook paths or matchers, and do not inherit whatever matcher the live config happens to use (a personal-data gate wired only to a narrow tool leaves disk writes ungated).
+- Under `--dangerously-skip-permissions` an `ask` decision is auto-resolved, so only a hard `deny` blocks a destructive command. The settings file carries an `env` block that sets `CLAUDE_DESTRUCTIVE_DENY_MODE`, which turns the destructive gate's terminal `ask` into a `deny`. The probe runs the gate under that env block and passes only on the hard deny.
+
+**Refusal cases — first match wins:**
+
+- **Not in a git repository.** Respond: `Prototype needs a git repo to branch a worktree from. Run this from inside one.`
+- **The `fresh-branch` skill is not installed.** Respond: `Prototype composes fresh-branch to make the sandbox worktree, and it is not installed. Install claude-dev-env first.`
+- **The `claude` CLI is not on PATH.** Respond: `The sandbox launches a headless claude session, and the claude CLI is not on PATH.`
+
+## Process
+
+Two phases. Run the sandbox phase first; run the promotion phase only when the POC succeeds and the user wants it shipped.
+
+### Phase 1 — Sandbox
+
+Follow `workflows/sandbox.md`. In short:
+
+1. Invoke the `fresh-branch` skill to create an isolated worktree off `origin/main`. Keep its returned `worktree_path` and `base_commit`.
+2. Run `scripts/build_sandbox_settings.py` to emit the minimal safety settings (personal-data and destructive-command gates only).
+3. Run `scripts/probe_sandbox_safety.py --settings <path>` and confirm both gates block. Do not continue on a non-zero exit.
+4. Run `scripts/launch_sandbox.py` to start the hookless `claude -p --bare` session in the worktree with those settings and the POC task.
+5. Read what the sandbox built. Decide whether the POC proves the idea.
+
+### Phase 2 — Promotion
+
+Run only in the normal, fully-hooked session — never inside the sandbox. Follow `workflows/promotion.md`, which drives the clean-room task seeds in `reference/promotion-tasks.md`: fresh branch off live `origin/main`, POC content as an uncommitted diff, cleanup and privacy sweep, `code-verifier` in a fresh context, then `/commit` and a draft PR handed to a PR-loop skill. State the two honest limitations from `reference/honest-limitations.md`.
+
+## Task seeding
+
+At the start of Phase 2, register every item in `reference/promotion-tasks.md` as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool). Work only from the task list. Mark each complete with evidence. Do not track promotion as a markdown checklist.
+
+## Sub-skills
+
+| Skill / agent | When | Produces | If missing |
+|---|---|---|---|
+| `fresh-branch` | Sandbox step 1; Promotion step 2 | isolated worktree JSON (`worktree_path`, `base_commit`, `repo_root`) | Refuse — see refusal cases |
+| `privacy-hygiene` | Promotion step 5 | personal-data and secret sweep of the diff | Warn; do a manual review before continuing |
+| `code-verifier` (agent) | Promotion step 6 | fresh-context verdict against the real diff; mints the commit-gate verdict | Stop; the commit gate will block anyway |
+| `/commit` (command) | Promotion step 7 | conventional commit + push | Commit and push by hand per `git-workflow` |
+| `autoconverge` (default; `pr-converge` or `bugteam` as alternatives) | Promotion step 9 | the PR converged to ready | Stop after the draft PR; tell the user to converge manually |
+
+## Degree of freedom
+
+Low on the skill's own mechanics — the launch flags and the promotion order are fragile with cliffs, so they live in scripts and a fixed task list, not in prose the agent reconstructs. High inside the sandbox — the sandboxed agent's build freedom is the whole point.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | This hub — principle, gotchas, when-applies, process, sub-skills, file index |
+| `workflows/sandbox.md` | Phase 1 steps: worktree, safety settings, probe, hookless launch |
+| `workflows/promotion.md` | Phase 2 steps: the clean-room re-verification that drives the promotion task seeds |
+| `reference/promotion-tasks.md` | Task-seed catalog for the clean-room protocol (register via the task tool) |
+| `reference/honest-limitations.md` | The two fixed statements to make on every promotion |
+| `scripts/build_sandbox_settings.py` | Emit the minimal safety `--settings`: resolve each hook's command from live settings, register it on the required matchers |
+| `scripts/launch_sandbox.py` | Launch the hookless `claude -p --bare` sandbox session in the worktree |
+| `scripts/probe_sandbox_safety.py` | Prove both safety gates block before trusting the sandbox |
+
+## Folder map
+
+- `SKILL.md` — hub.
+- `workflows/` — the two phase workflows.
+- `reference/` — promotion task seeds and the honest-limitation statements.
+- `scripts/` — the settings builder, the launcher, the safety probe, their `prototype_scripts_constants` package, and paired tests.

package/skills/prototype/reference/honest-limitations.md

@@ -0,0 +1,23 @@
+# Honest limitations of a promoted prototype
+
+State both of these to the user, in these terms, whenever a proof-of-concept is promoted. Do not soften or drop them. They are the price of building without standards gates.
+
+## 1. Write-time code rules never ran on this code
+
+`code_rules_enforcer` is a Write/Edit gate: it checks content as it is written. Prototype code is built under `--bare`, so that gate never fired, and content brought into promotion as a git diff (apply, checkout, cherry-pick) does not pass through it either.
+
+Standards re-engage on promotion through three surfaces that stand in for the write-time hook:
+
+- the `code-verifier` agent, in a fresh context, deriving and running the named gates against the real diff;
+- the `privacy-hygiene` sweep for personal data and secrets;
+- the pull-request review (AGENTS.md criteria and any PR-loop reviewers).
+
+Say plainly: the write-time rule engine did not see this code; the verifier and review are what cover it.
+
+## 2. TDD ordering is waived on promoted prototype lines
+
+The sandbox agent wrote code first and tests, if any, after. Red-green-refactor ordering did not happen. So the honest claim on promoted prototype code is exactly this, and nothing more:
+
+> code-verifier passed, privacy swept, review passed — TDD ordering waived.
+
+Do not claim red-green compliance on these lines. A prototype is a reference build, not a test-first build. Fred Brooks: plan to throw one away. Promotion re-verifies the code and often rewrites it to standard; expect real work in the verifier repair loop, not a rubber stamp.

package/skills/prototype/reference/promotion-tasks.md

@@ -0,0 +1,23 @@
+# Promotion task seeds (clean-room protocol)
+
+Register every numbered item below as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool) at the start of the promotion phase. Work only from the task list. Mark each complete only with evidence — a command result, a path, a verdict, or a skill's return. This is not a checkbox board; it is a seed catalog for the task tool.
+
+Promotion runs in the **normal, fully-hooked session** — never inside the `--bare` sandbox. Nothing from the sandbox history is carried; only its file content is re-applied and re-verified.
+
+1. **Confirm the prototype is worth promoting.** The sandbox build works and the user (or the standing goal) wants it shipped. Evidence: the working behavior observed, one sentence on what the POC proves.
+
+2. **Fresh branch off live upstream.** Re-fetch `origin/main` and branch from it via the `fresh-branch` skill. Evidence: the returned `base_commit` matches current `origin/main`. This starts clean history and keeps the work based on live upstream.
+
+3. **Bring prototype content as an uncommitted working-tree diff, by allowlist.** Take the sandbox diff against its `base_commit` and copy only the product files you intend to ship into the fresh branch's working tree. Do NOT cherry-pick or merge the sandbox commits, and do NOT bulk-copy the worktree. Exclude the sandbox settings file (`.prototype-sandbox-settings.json`) and every scratch, debug, or artifact file the POC produced — name the files you are bringing, not the ones you are dropping. Evidence: the allowlist of copied paths; `git status` shows only those unstaged; `git log` shows no sandbox commits.
+
+4. **Cleanup pass.** Remove every scratch file, debug dump, and temp helper the prototype created (see the `cleanup-temp-files` rule). Evidence: the removed paths, or a stated "none created".
+
+5. **Privacy sweep.** Run the `privacy-hygiene` skill over the full applied working tree, not only the diff — a POC that pulled live data can leave a secret in a file the diff view hides. Evidence: its clean report, or the leak it found and how it was removed. If the skill is missing, do a manual PII and secret review and say so.
+
+6. **Verify in a fresh context.** Spawn the `code-verifier` agent against the real diff. Expect findings and a repair loop — the code was un-TDD'd. Evidence: the verifier's clean verdict, and a note of what it made you fix. Do not skip this on the belief that the sandbox agent already tested it.
+
+7. **Commit and open a draft PR.** Only on a clean verdict, run `/commit` (which mints the commit-gate verdict and pushes), then open a draft PR per the `git-workflow` rule. Evidence: the commit hash and the PR URL.
+
+8. **State the honest limitations.** Post the two statements from `reference/honest-limitations.md` — write-time rules never ran; TDD ordering waived — in the PR body or to the user. Evidence: the text was included.
+
+9. **Hand to a PR-loop skill.** Hand the PR to `autoconverge` by default — one autonomous run to ready. Reach for `pr-converge` when paced ticks fit better, or `bugteam` for an open-loop audit-fix. Evidence: the skill was invoked, or the user chose to converge manually.