claude-dev-env 2.3.0 → 2.4.0

package/skills/fresh-branch/scripts/test_create_fresh_branch.py

@@ -146,6 +146,21 @@ def build_repo_with_origin(workspace_path: Path) -> Path:
     return clone_path
 
 
+def read_branch_config(
+    repository_path: Path,
+    branch_name: str,
+    config_leaf: str,
+) -> str:
+    completed = subprocess.run(
+        ["git", "config", "--get", f"branch.{branch_name}.{config_leaf}"],
+        cwd=str(repository_path),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
 def read_head_branch(repository_path: Path) -> str:
     completed = run_git(["rev-parse", "--abbrev-ref", "HEAD"], repository_path)
     return completed.stdout.strip()
@@ -156,6 +171,14 @@ def read_head_commit(repository_path: Path) -> str:
     return completed.stdout.strip()
 
 
+def read_remote_main_commit(repository_path: Path) -> str:
+    completed = run_git(
+        ["ls-remote", REMOTE_NAME, f"refs/heads/{MAIN_BRANCH_NAME}"],
+        repository_path,
+    )
+    return completed.stdout.split()[0]
+
+
 class TestResolveAgentSlug:
     def should_prefer_flag_over_environment(
         self,
@@ -512,6 +535,81 @@ class TestCreateFreshBranchIntegration:
         assert read_head_commit(worktree_path) != local_main_commit
 
 
+class TestWorktreeBranchTracking:
+    def should_leave_new_branch_without_an_upstream(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        agent_scratch_parent = tmp_path / "agent-scratch"
+        monkeypatch.setattr(module.sys, "platform", "linux")
+        monkeypatch.setattr(
+            module.tempfile,
+            "gettempdir",
+            lambda: str(agent_scratch_parent),
+        )
+        success_payload = module.create_fresh_branch(
+            branch_name="fix/no-upstream",
+            repo_path=repository_path,
+            agent_slug="claude",
+            base_ref=DEFAULT_BASE_REF,
+        )
+        worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
+        assert read_head_branch(worktree_path) == "fix/no-upstream"
+        assert read_branch_config(repository_path, "fix/no-upstream", "merge") == ""
+        assert read_branch_config(repository_path, "fix/no-upstream", "remote") == ""
+
+    def should_not_aim_a_bare_push_at_main_under_push_default_upstream(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        module = load_create_fresh_branch_module()
+        repository_path = build_repo_with_origin(tmp_path / "repo")
+        empty_hooks_path = tmp_path / "repo" / "empty-hooks"
+        run_git(
+            ["config", "push.default", "upstream"],
+            repository_path,
+            empty_hooks_path=empty_hooks_path,
+        )
+        agent_scratch_parent = tmp_path / "agent-scratch"
+        monkeypatch.setattr(module.sys, "platform", "linux")
+        monkeypatch.setattr(
+            module.tempfile,
+            "gettempdir",
+            lambda: str(agent_scratch_parent),
+        )
+        success_payload = module.create_fresh_branch(
+            branch_name="feature/silent-push",
+            repo_path=repository_path,
+            agent_slug="claude",
+            base_ref=DEFAULT_BASE_REF,
+        )
+        worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
+        (worktree_path / SEED_FILE_NAME).write_text("drive-by\n", encoding="utf-8")
+        run_git(["add", SEED_FILE_NAME], worktree_path, empty_hooks_path=empty_hooks_path)
+        run_git(
+            ["commit", "-m", "work on the feature branch"],
+            worktree_path,
+            empty_hooks_path=empty_hooks_path,
+        )
+        origin_main_before = read_remote_main_commit(repository_path)
+        push_attempt = subprocess.run(
+            ["git", "-c", f"core.hooksPath={empty_hooks_path}", "push"],
+            cwd=str(worktree_path),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        assert push_attempt.returncode != 0, (
+            "bare push should be refused, but it succeeded:\n"
+            f"{push_attempt.stdout}{push_attempt.stderr}"
+        )
+        assert read_remote_main_commit(repository_path) == origin_main_before
+
+
 class TestMainCli:
     def should_print_success_json_and_exit_zero(
         self,

package/skills/fresh-branch/scripts/test_fresh_branch_git_commands.py

@@ -0,0 +1,310 @@
+"""Behavioral tests for fresh_branch_git_commands using real temporary git repos."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+from fresh_branch_git_commands import (
+    assert_git_accepts_branch_name,
+    build_worktree_add_arguments,
+    create_worktree_branch,
+    fetch_base_ref,
+    is_ref_present,
+    read_failure_text,
+    resolve_base_commit,
+    resolve_repo_root,
+    run_git,
+    split_remote_ref,
+)
+
+GIT_USER_NAME = "fresh-branch-test"
+GIT_USER_EMAIL = "fresh-branch-test@example.com"
+MAIN_BRANCH_NAME = "main"
+SEED_FILE_NAME = "README.md"
+SEED_FILE_CONTENTS = "seed\n"
+
+
+def build_repo(workspace_path: Path) -> Path:
+    workspace_path.mkdir(parents=True, exist_ok=True)
+    empty_hooks_path = workspace_path / "empty-hooks"
+    empty_hooks_path.mkdir()
+    hooks_argument = ["-c", f"core.hooksPath={empty_hooks_path}"]
+    subprocess.run(
+        ["git", *hooks_argument, "init", "-b", MAIN_BRANCH_NAME, str(workspace_path)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    for each_pair in (
+        ("user.name", GIT_USER_NAME),
+        ("user.email", GIT_USER_EMAIL),
+        ("commit.gpgsign", "false"),
+    ):
+        subprocess.run(
+            ["git", *hooks_argument, "config", *each_pair],
+            cwd=str(workspace_path),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    (workspace_path / SEED_FILE_NAME).write_text(SEED_FILE_CONTENTS, encoding="utf-8")
+    subprocess.run(
+        ["git", *hooks_argument, "add", SEED_FILE_NAME],
+        cwd=str(workspace_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    subprocess.run(
+        ["git", *hooks_argument, "commit", "-m", "initial commit"],
+        cwd=str(workspace_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return workspace_path
+
+
+def build_clone_with_origin(workspace_path: Path) -> tuple[Path, Path]:
+    seed_path = build_repo(workspace_path / "seed")
+    empty_hooks_path = seed_path / "empty-hooks"
+    hooks_argument = ["-c", f"core.hooksPath={empty_hooks_path}"]
+    bare_origin = workspace_path / "origin.git"
+    subprocess.run(
+        ["git", *hooks_argument, "clone", "--bare", str(seed_path), str(bare_origin)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    clone_path = workspace_path / "clone"
+    subprocess.run(
+        ["git", *hooks_argument, "clone", str(bare_origin), str(clone_path)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    for each_pair in (
+        ("user.name", GIT_USER_NAME),
+        ("user.email", GIT_USER_EMAIL),
+        ("commit.gpgsign", "false"),
+    ):
+        subprocess.run(
+            ["git", *hooks_argument, "config", *each_pair],
+            cwd=str(clone_path),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    return clone_path, bare_origin
+
+
+def advance_origin_main(workspace_path: Path, bare_origin: Path) -> str:
+    pusher_path = workspace_path / "pusher"
+    empty_hooks_path = workspace_path / "seed" / "empty-hooks"
+    hooks_argument = ["-c", f"core.hooksPath={empty_hooks_path}"]
+    subprocess.run(
+        ["git", *hooks_argument, "clone", str(bare_origin), str(pusher_path)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    for each_pair in (
+        ("user.name", GIT_USER_NAME),
+        ("user.email", GIT_USER_EMAIL),
+        ("commit.gpgsign", "false"),
+    ):
+        subprocess.run(
+            ["git", *hooks_argument, "config", *each_pair],
+            cwd=str(pusher_path),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    (pusher_path / SEED_FILE_NAME).write_text("advanced\n", encoding="utf-8")
+    subprocess.run(
+        ["git", *hooks_argument, "commit", "-am", "advance main"],
+        cwd=str(pusher_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    subprocess.run(
+        ["git", *hooks_argument, "push", "origin", MAIN_BRANCH_NAME],
+        cwd=str(pusher_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    completed = subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=str(pusher_path),
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def read_branch_config(
+    repository_path: Path,
+    branch_name: str,
+    config_leaf: str,
+) -> str:
+    completed = subprocess.run(
+        ["git", "config", "--get", f"branch.{branch_name}.{config_leaf}"],
+        cwd=str(repository_path),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+class TestBuildWorktreeAddArguments:
+    def test_pass_no_track_so_the_new_branch_gets_no_upstream(self) -> None:
+        all_arguments = build_worktree_add_arguments(
+            "fix/x",
+            Path("/tmp/agent/fix/x"),
+            "origin/main",
+        )
+        assert "--no-track" in all_arguments
+
+    def test_order_arguments_the_way_git_worktree_add_expects(self) -> None:
+        all_arguments = build_worktree_add_arguments(
+            "fix/x",
+            Path("/tmp/agent/fix/x"),
+            "origin/main",
+        )
+        assert all_arguments[:4] == ["worktree", "add", "-b", "fix/x"]
+        assert all_arguments[-1] == "origin/main"
+        assert all_arguments[-2] == str(Path("/tmp/agent/fix/x"))
+
+
+class TestSplitRemoteRef:
+    def test_split_an_origin_ref(self) -> None:
+        assert split_remote_ref("origin/main") == ("origin", "main")
+
+    def test_split_a_non_origin_remote_ref(self) -> None:
+        assert split_remote_ref("upstream/dev") == ("upstream", "dev")
+
+    def test_default_a_bare_name_to_origin(self) -> None:
+        assert split_remote_ref("main") == ("origin", "main")
+
+    def test_keep_slashes_inside_the_branch_name(self) -> None:
+        assert split_remote_ref("origin/fix/nested") == ("origin", "fix/nested")
+
+
+class TestAssertGitAcceptsBranchName:
+    def test_accept_a_conventional_branch_name(self) -> None:
+        assert assert_git_accepts_branch_name("fix/example-one") is None
+
+    def test_reject_a_name_git_refuses(self) -> None:
+        with pytest.raises(ValueError, match="relative path"):
+            assert_git_accepts_branch_name("fix..example")
+
+
+class TestResolveRepoRoot:
+    def test_return_the_toplevel_for_a_nested_path(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        nested_path = repository_path / "nested"
+        nested_path.mkdir()
+        assert resolve_repo_root(nested_path).resolve() == repository_path.resolve()
+
+    def test_raise_outside_a_repository(self, tmp_path: Path) -> None:
+        plain_directory = tmp_path / "plain"
+        plain_directory.mkdir()
+        with pytest.raises(RuntimeError, match="git repository"):
+            resolve_repo_root(plain_directory)
+
+
+class TestIsRefPresent:
+    def test_find_a_local_branch(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        assert is_ref_present(repository_path, MAIN_BRANCH_NAME) is True
+
+    def test_not_find_an_absent_ref(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        assert is_ref_present(repository_path, "origin/nowhere") is False
+
+
+class TestReadFailureText:
+    def test_prefer_stderr(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        completed = run_git(["rev-parse", "does-not-exist"], repository_path)
+        assert completed.returncode != 0
+        assert "does-not-exist" in read_failure_text(completed)
+
+
+class TestFetchBaseRef:
+    def test_bring_the_remote_tip_into_the_clone(self, tmp_path: Path) -> None:
+        clone_path, bare_origin = build_clone_with_origin(tmp_path / "workspace")
+        advanced_commit = advance_origin_main(tmp_path / "workspace", bare_origin)
+        fetch_base_ref(clone_path, "origin/main")
+        assert is_ref_present(clone_path, "origin/main") is True
+        assert resolve_base_commit(clone_path, "origin/main") == advanced_commit
+
+    def test_raise_for_a_remote_branch_that_does_not_exist(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        clone_path, _bare_origin = build_clone_with_origin(tmp_path / "workspace")
+        with pytest.raises(RuntimeError, match="git fetch failed"):
+            fetch_base_ref(clone_path, "origin/nowhere")
+
+
+class TestResolveBaseCommit:
+    def test_return_the_sha_at_the_ref(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        head_commit = run_git(["rev-parse", "HEAD"], repository_path).stdout.strip()
+        assert resolve_base_commit(repository_path, MAIN_BRANCH_NAME) == head_commit
+
+    def test_raise_for_an_unresolvable_ref(self, tmp_path: Path) -> None:
+        repository_path = build_repo(tmp_path / "repo")
+        with pytest.raises(RuntimeError, match="could not resolve base commit"):
+            resolve_base_commit(repository_path, "refs/heads/nowhere")
+
+
+class TestCreateWorktreeBranch:
+    def test_create_the_branch_at_the_base_ref_with_no_upstream(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        clone_path, _bare_origin = build_clone_with_origin(tmp_path / "workspace")
+        origin_tip = resolve_base_commit(clone_path, "origin/main")
+        worktree_path = tmp_path / "worktrees" / "fix" / "created"
+        create_worktree_branch(
+            clone_path,
+            branch_name="fix/created",
+            worktree_path=worktree_path,
+            base_ref="origin/main",
+        )
+        assert worktree_path.is_dir()
+        assert resolve_base_commit(worktree_path, "HEAD") == origin_tip
+        assert read_branch_config(clone_path, "fix/created", "merge") == ""
+        assert read_branch_config(clone_path, "fix/created", "remote") == ""
+
+    def test_raise_when_the_branch_already_exists(self, tmp_path: Path) -> None:
+        clone_path, _bare_origin = build_clone_with_origin(tmp_path / "workspace")
+        first_path = tmp_path / "worktrees" / "dup-one"
+        second_path = tmp_path / "worktrees" / "dup-two"
+        create_worktree_branch(
+            clone_path,
+            branch_name="fix/dup",
+            worktree_path=first_path,
+            base_ref="origin/main",
+        )
+        with pytest.raises(RuntimeError, match="worktree add failed"):
+            create_worktree_branch(
+                clone_path,
+                branch_name="fix/dup",
+                worktree_path=second_path,
+                base_ref="origin/main",
+            )

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.