claude-dev-env 4.2.0 → 7.0.0

package/.agents/skills/pull-request/scripts/test_recover_legacy_author.py

@@ -0,0 +1,221 @@
+"""Contract tests for explicit legacy GitHub author recovery."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from unittest.mock import Mock
+
+import pytest
+
+_SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
+
+import recover_legacy_author
+
+CURRENT_TIME_SECONDS = 2_000_000.0
+CURRENT_USER_ID = 41
+LEGACY_ACCOUNT = "previous-account"
+OTHER_ACCOUNT = "other-account"
+STATE_FILENAME = "gh_pr_author_swap_session-a.json"
+
+
+def _completion(
+    code: int = 0, stdout: str = "", stderr: str = ""
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.CompletedProcess([], code, stdout, stderr)
+
+
+def _write_state(
+    directory: Path,
+    *,
+    filename: str = STATE_FILENAME,
+    payload: object | None = None,
+    age_seconds: float = 1801.0,
+) -> Path:
+    state_file = directory / filename
+    state_payload = {"original_account": LEGACY_ACCOUNT} if payload is None else payload
+    state_file.write_text(json.dumps(state_payload), encoding="utf-8")
+    os.utime(
+        state_file,
+        (CURRENT_TIME_SECONDS - age_seconds, CURRENT_TIME_SECONDS - age_seconds),
+    )
+    if hasattr(os, "getuid"):
+        state_file.chmod(0o600)
+    return state_file
+
+
+def _run(
+    state_file: Path,
+    command_runner: Callable[..., subprocess.CompletedProcess[str]],
+    *,
+    confirm_inactive: bool = True,
+) -> int:
+    all_arguments = [str(state_file)]
+    if confirm_inactive:
+        all_arguments.append("--confirm-inactive")
+    return recover_legacy_author.main(
+        all_arguments,
+        now_seconds=CURRENT_TIME_SECONDS,
+        current_user_id=os.getuid() if hasattr(os, "getuid") else None,
+        command_runner=command_runner,
+    )
+
+
+def test_success_restores_selected_record_and_preserves_neighbor(
+    tmp_path: Path,
+) -> None:
+    selected_file = _write_state(tmp_path)
+    neighbor_file = _write_state(
+        tmp_path,
+        filename="gh_pr_author_swap_session-b.json",
+        payload={"original_account": OTHER_ACCOUNT},
+    )
+    command_runner = Mock(return_value=_completion())
+    assert _run(selected_file, command_runner) == 0
+    command_runner.assert_called_once_with(
+        ["gh", "auth", "switch", "--user", LEGACY_ACCOUNT],
+        capture_output=True,
+        check=False,
+        shell=False,
+        text=True,
+    )
+    assert not selected_file.exists()
+    assert neighbor_file.exists()
+
+
+def test_unconfirmed_record_is_unresolved_without_side_effects(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path)
+    command_runner = Mock()
+    assert _run(state_file, command_runner, confirm_inactive=False) == 3
+    assert "confirm inactive" in capsys.readouterr().err
+    command_runner.assert_not_called()
+    assert state_file.exists()
+
+
+def test_active_record_is_rejected_without_side_effects(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path, age_seconds=10.0)
+    command_runner = Mock()
+    assert _run(state_file, command_runner) == 2
+    assert "record is active" in capsys.readouterr().err
+    command_runner.assert_not_called()
+    assert state_file.exists()
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        [],
+        {},
+        {"original_account": ""},
+        {"original_account": 7},
+        {"original_account": LEGACY_ACCOUNT, "extra": True},
+    ],
+)
+def test_invalid_schema_is_rejected(
+    tmp_path: Path, payload: object, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path, payload=payload)
+    command_runner = Mock()
+    assert _run(state_file, command_runner) == 2
+    assert "record is invalid" in capsys.readouterr().err
+    command_runner.assert_not_called()
+    assert state_file.exists()
+
+
+def test_invalid_utf8_is_rejected(tmp_path: Path) -> None:
+    state_file = _write_state(tmp_path)
+    state_file.write_bytes(b"\xff")
+    os.utime(state_file, (CURRENT_TIME_SECONDS - 1801, CURRENT_TIME_SECONDS - 1801))
+    command_runner = Mock()
+    assert _run(state_file, command_runner) == 2
+    command_runner.assert_not_called()
+    assert state_file.exists()
+
+
+def test_wrong_filename_is_rejected(tmp_path: Path) -> None:
+    state_file = _write_state(tmp_path, filename="other.json")
+    command_runner = Mock()
+    assert _run(state_file, command_runner) == 2
+    command_runner.assert_not_called()
+
+
+def test_symlink_is_rejected(tmp_path: Path) -> None:
+    target_file = _write_state(tmp_path)
+    link_file = tmp_path / "gh_pr_author_swap_link.json"
+    try:
+        link_file.symlink_to(target_file)
+    except OSError as error:
+        pytest.skip(f"symlink unavailable: {error}")
+    command_runner = Mock()
+    assert _run(link_file, command_runner) == 2
+    command_runner.assert_not_called()
+    assert target_file.exists()
+
+
+def test_failed_restore_preserves_record_and_hides_child_output(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path)
+    command_runner = Mock(
+        return_value=_completion(1, LEGACY_ACCOUNT, f"unsafe {LEGACY_ACCOUNT}")
+    )
+    assert _run(state_file, command_runner) == 1
+    captured = capsys.readouterr()
+    assert captured.err == "error: GitHub account restore failed\n"
+    assert LEGACY_ACCOUNT not in captured.out + captured.err
+    assert state_file.exists()
+
+
+def test_restore_launch_failure_preserves_record(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path)
+    command_runner = Mock(side_effect=OSError("unavailable"))
+    assert _run(state_file, command_runner) == 1
+    assert capsys.readouterr().err == "error: GitHub account restore failed\n"
+    assert state_file.exists()
+
+
+def test_changed_record_after_restore_is_preserved(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path)
+
+    def change_record(
+        all_arguments: list[str], **keyword_arguments: object
+    ) -> subprocess.CompletedProcess[str]:
+        state_file.write_text(
+            json.dumps({"original_account": OTHER_ACCOUNT}), encoding="utf-8"
+        )
+        return _completion()
+
+    assert _run(state_file, change_record) == 1
+    assert "record changed" in capsys.readouterr().err
+    assert state_file.exists()
+
+
+def test_secure_posix_metadata_requires_regular_owner_mode() -> None:
+    regular_secure_mode = stat.S_IFREG | 0o600
+    assert recover_legacy_author._posix_metadata_is_secure(
+        regular_secure_mode, CURRENT_USER_ID, CURRENT_USER_ID
+    )
+    assert not recover_legacy_author._posix_metadata_is_secure(
+        regular_secure_mode, CURRENT_USER_ID + 1, CURRENT_USER_ID
+    )
+    assert not recover_legacy_author._posix_metadata_is_secure(
+        stat.S_IFREG | 0o644, CURRENT_USER_ID, CURRENT_USER_ID
+    )
+    assert not recover_legacy_author._posix_metadata_is_secure(
+        stat.S_IFLNK | 0o600, CURRENT_USER_ID, CURRENT_USER_ID
+    )

package/.agents/skills/skill-builder/SKILL.md

@@ -1,202 +1,9 @@
 ---
 name: skill-builder
 disable-model-invocation: true
-description: >-
-  Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose
-  sub-skills, polish description triggers, enforce deterministic scripts. Triggers:
-  build a skill, new skill workflow, improve this skill, optimize skill description,
-  skill development lifecycle, skill modularity, skill composition, description
-  trigger catalog, deterministic skill scripts.
+description: Placeholder for the skill-builder rework to follow pstack philosophy.
 ---
 
-# Skill Builder
+# Skill builder
 
-**Core principle:** Best-practice-driven craftsman. Knows every proven pattern, applies them intentionally, self-audits after building. The expert that enforces craft standards.
-
-Sources: [Anthropic best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Lessons from Building Claude Code](references/thariq-x-post-skills.json), model skills (bugteam, pr-converge).
-
-## Gotchas
-
-Highest-signal content. Append a bullet each time a skill build fails in a new way.
-
-> "The highest-signal content in any skill is the Gotchas section. These sections should be built up from common failure points that Claude runs into when using your skill."
-
-- Story-form `description` burns always-on context and weakens selection — rewrite to capability stem + `Triggers:` list (`description-field.md`).
-- Multi-capability packages fail modularity audit — split or thin orchestrator + named sub-skills (`skill-modularity.md`).
-- Skipping the composition plan before Write reintroduces silent reimplementation of peer skills.
-- Deterministic steps written only as prose (fenced source, giant `rg` lines, multi-step mechanical sequences) fail audit — extract to `scripts/` / `workflow/` / `templates/` / `reference/` (`deterministic-elements.md`).
-- Markdown `- [ ]` checklists as the agent's progress board fail audit when a task tool exists — seed tasks via `TaskCreate` / `TodoWrite` (`deterministic-elements.md`).
-
-## When this skill applies
-
-Trigger for requests to **build**, **improve**, or **polish** a skill. This skill orchestrates the process — it classifies, scaffolds, gathers context, delegates writing to the `skill-writer-agent` agent, and self-audits the result.
-
-For quick skill syntax questions or one-off SKILL.md edits, spawn the `skill-writer-agent` agent directly.
-
-**Refusal cases — first match wins:**
-
-- **No clear task or domain.** Respond exactly: `What should this skill do? Give me a one-sentence description of the capability.`
-
-## The Process
-
-Each workflow file provides step-by-step instructions. After routing below, open the corresponding workflow file and follow it.
-
-### Routing
-
-Assess the user’s intent:
-
-**Creating a new skill?**
-Read `${CLAUDE_SKILL_DIR}/workflows/new-skill.md` and follow it.
-
-**Improving an existing skill?**
-Read `${CLAUDE_SKILL_DIR}/workflows/improve-skill.md` and follow it.
-
-**Final polish only (description optimization, trigger audit)?**
-Read `${CLAUDE_SKILL_DIR}/workflows/polish-skill.md` and follow it.
-
-**Ambiguous?** Ask: "Are you creating a new skill, improving an existing one, or doing a final polish pass?"
-
-### The Claude A / Claude B pattern
-
-You and the user are **Claude A** — the expert who designs and refines the skill. Subagents running the built skill on real tasks are **Claude B** — the agent using the skill to perform actual work.
-
-> "Work with one instance of Claude (‘Claude A’) to create a Skill that is used by other instances (‘Claude B’). Claude A helps you design and refine instructions, while Claude B tests them in real tasks."
-
-The feedback loop: observe Claude B’s behavior, bring insights back, refine the skill, test again.
-
-## Skill type routing
-
-> "After cataloging all of our skills, we noticed they cluster into a few recurring categories."
-
-Classify into one of 9 types — type sets folder structure. Taxonomy and layouts: [`references/skill-types.md`](references/skill-types.md).
-
-## Principles
-
-These are non-negotiable. Every skill must satisfy them. Enforce via [`references/self-audit-checklist.md`](references/self-audit-checklist.md).
-
-### Concision and defaults
-
-> "Default assumption: Claude is already very smart. Only add context Claude doesn’t already have."
-
-> "Don’t State the Obvious — focus on information that pushes Claude out of its normal way of thinking."
-
-Challenge each sentence: "Does Claude really need this?"
-
-### Degree of freedom
-
-> "Match the level of specificity to the task’s fragility and variability."
-
-High freedom (text guidance) for open fields. Low freedom (exact scripts, no parameters) for narrow bridges with cliffs.
-
-> "Avoid Railroading Claude — give Claude the information it needs, but give it the flexibility to adapt."
-
-### Progressive disclosure
-
-Hub pattern, line caps, one-level references, TOC and path rules: [`references/progressive-disclosure.md`](references/progressive-disclosure.md).
-
-### Modularity and composition
-
-One skill = one capability. Multi-step work invokes **sub-skills** (peer skills) by name. Prefer compose over reimplement. Full rules: [`references/skill-modularity.md`](references/skill-modularity.md).
-
-> "You can just reference other skills by name, and the model will invoke them if they are installed."
-
-New-skill Gather records a composition plan before write. Self-audit modularity items are mandatory.
-
-### Description field (trigger catalog)
-
-The frontmatter `description` is **selection metadata** pre-loaded for every skill. Write a **trigger catalog**, not a story: short capability stem + concrete trigger phrases. No narrative, benefits language, or process dump.
-
-Full rules: [`references/description-field.md`](references/description-field.md). Polish workflow Step 1 is the dedicated rewrite pass.
-
-> "The description field is not a summary — it’s a description of when to trigger."
-
-### Gotchas
-
-Mandatory highest-signal section (see Gotchas above). Capture real failure modes; self-audit requires the section present and actionable.
-
-### Templates and examples
-
-> "Provide templates for output format" and "Examples help Claude understand the desired style and level of detail more clearly than descriptions alone."
-
-Use the template pattern for structured outputs. Use the examples pattern (input/output pairs) for style-dependent work.
-
-### Workflows and task seeds
-
-Multi-step required work is a **task seed list** (plain bullets in a reference file) plus an instruction to register each item on the host task tool (`TaskCreate`, `TodoWrite`, or equivalent). Agents work the task list and mark complete with evidence.
-
-Do **not** ship markdown `- [ ]` boards as the completion protocol when a task tool is available. Do **not** say "copy this checklist into your response and check it off."
-
-Quality-critical operations still use feedback loops (run validator → fix → repeat). Spec: [`references/deterministic-elements.md`](references/deterministic-elements.md) (Task-tool tracking).
-
-### Scripts
-
-> "Handle error conditions rather than punting to Claude." "Make clear whether Claude should execute the script or read it as reference."
-
-> "One of the most powerful tools you can give Claude is code — letting Claude spend its turns on composition rather than reconstructing boilerplate."
-
-### Deterministic elements (mandatory classification)
-
-Any skill element that is **deterministic** (same inputs → same outputs; machine-checkable success) ships as code, a fixed artifact, or a **session task seed** — not prose-only steps or markdown checkbox boards. Judgment, routing, and refusals stay in markdown.
-
-Full rules, inventory table, task-tool tracking, CODE_RULES bar for skill scripts, and anti-patterns: [`references/deterministic-elements.md`](references/deterministic-elements.md).
-
-New-skill Gather records a deterministic-elements inventory before write. Self-audit items register as session tasks and are mandatory on every delivery (pure-judgment skills mark script rows N/A with evidence).
-
-### Setup and memory
-
-> "Think through the Setup — some skills may need to be set up with context from the user. A good pattern is to store this in a config.json file."
-
-> "Data stored in the skill directory may be deleted when you upgrade the skill, so store persistent data in `${CLAUDE_PLUGIN_DATA}`."
-
-### Constraints and refusal cases
-
-> bugteam pattern — non-negotiables separated from guidance, with design rationale. Explicit "first match wins" refusal conditions.
-
-### Anti-patterns
-
-> No Windows paths. Don’t offer too many options — provide a default with escape hatch. Avoid time-sensitive claims. Use consistent terminology. No deeply nested references.
-
-Also: story-form descriptions; monolith multi-capability skills; silent reimplementation of peer skills; nested folders used as fake sub-skills; deterministic logic only in prose or fenced source; markdown `- [ ]` as the agent's work tracker.
-
-## Self-audit
-
-After every build, improvement, or polish pass, load `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`, **register every bullet as a session task**, and complete each with evidence. Every item must pass before delivery. Fix failures, then re-audit.
-
-## Delegation to skill-writer-agent
-
-skill-builder orchestrates; the `skill-writer-agent` agent authors. The caller spawns it with `Agent(subagent_type="skill-writer-agent", ...)`. The handoff packet from Step 4 must include:
-
-- Skill type and folder structure
-- Gap analysis or observation findings (composition plan + description triggers + deterministic inventory)
-- Degree of freedom assessment
-- Initial gotchas
-- Composition plan: related skills, sub-skills to invoke, split decisions
-- Description trigger catalog: capability stem + trigger phrases (not prose)
-- Deterministic elements inventory: each process step classified; code paths + paired tests
-- Any constraints
-
-See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact patterns.
-
-## File index
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | This hub — principles, process, routing, file index |
-| `references/skill-types.md` | 9-type taxonomy with folder structures per type |
-| `references/progressive-disclosure.md` | Folder conventions, hub pattern, 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/deterministic-elements.md` | Deterministic steps as code/task seeds; CODE_RULES; no markdown checkbox boards |
-| `references/self-audit-checklist.md` | Post-build audit task seeds (register via TaskCreate / TodoWrite) |
-| `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
-| `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, deterministic inventory |
-
-## Folder map
-
-- `SKILL.md` — hub.
-- `references/` — best-practice specifications and the audit checklist.
-- `workflows/` — step-by-step workflows for each lifecycle phase.
-- `templates/` — reusable templates for skill artifacts.
+TODO: Rework to follow pstack philosophy.

package/.agents/skills/test-runner/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: test-runner
+description: >-
+  Run pytest or Playwright through the repository's test command.
+  Checks Django and Playwright readiness before launching the
+  selected child process. Use when running tests in a repository with local
+  Django or frontend services.
+---
+
+# test-runner
+
+Run Django and Playwright readiness checks, then launch the selected test
+command. Pass one supported runner after `--`. The command forwards those
+arguments without a shell.
+
+## Command
+
+Run from the repository that owns the tests:
+
+```text
+python "${CLAUDE_SKILL_DIR}/scripts/run_tests.py" -- python -m pytest <pytest-arguments>
+python "${CLAUDE_SKILL_DIR}/scripts/run_tests.py" -- npx playwright test <playwright-arguments>
+```
+
+Use `--project <path>` when the test repository is not the current directory:
+
+```text
+python "${CLAUDE_SKILL_DIR}/scripts/run_tests.py" --project "<repository>" -- python -m pytest <pytest-arguments>
+```
+
+The supported runner forms are `pytest`, `python -m pytest`, `playwright test`,
+and `npx playwright test`. The child receives the exact arguments after `--`,
+inherits the current environment, writes to the current output streams, runs
+with the selected project as its working directory, and returns its exit
+status.
+
+## Preflight
+
+The command returns nonzero and launches no child when a required check fails.
+
+- A pytest run in a project without `manage.py` runs without preflight.
+- A pytest run in a Django project requires `db.sqlite3` and a healthy Django
+  server. The URL defaults to `http://localhost:8000`. A URL in the child
+  arguments overrides that default.
+- A Playwright run checks its target server, validates a detected Django
+  `runserver` process uses `--test-db`, rejects conflicting Django servers from
+  different worktrees, and uses the URL default `http://localhost:3000`.
+- When the project contains `frontend/`, the command runs `npm run build` in
+  that directory, then `python manage.py collectstatic --noinput` in the
+  project directory before Playwright starts.
+
+The command does not parse shell syntax. Keep pipes, redirects, `cd`, and
+background operators outside this command. Run this command directly so its
+exit status reaches the caller.
+
+## Unsupported commands
+
+Use the normal runner for anything else. This command accepts only the four
+runner forms listed above. It does not install dependencies, start a server,
+run migrations, or repair a failed preflight.
+
+## Files
+
+- `SKILL.md` covers invocation, checks, and the command boundary.
+- `scripts/run_tests.py` parses the command, runs preflight, and launches the child.
+- `scripts/preflight_checks.py` runs Django and Playwright readiness checks.
+- `scripts/test_run_tests.py` covers the command and preflight.
+- `scripts/test_preflight_checks.py` covers the readiness checks.
+- `scripts/test_runner_constants/` holds command names, messages, and limits.