claude-dev-env 2.28.1 → 2.29.0

package/scripts/AGENTS.md

@@ -1,56 +1 @@
-# scripts
 
-Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each script is a standalone tool a user or hook can invoke directly.
-
-## Scripts
-
-| File | Purpose |
-|---|---|
-| `claude_chain_runner.py` | Runs a `claude` invocation through a fallback chain (`~/.claude/claude-chain.json`) with `--routing-mode usage_ranked` (default: probe weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, highest remaining first) or `ordered_account` (config list order; non-usage failures stop as `advisor_blocked`); falls over only on a usage-limit failure; returns `terminal_status` / optional `session_id` on the outcome; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
-| `claude_chain_usage.py` | Reports remaining weekly usage for every account in `~/.claude/claude-chain.json` via the usage-pause OAuth probe; prints JSON (`accounts` with `weekly_remaining_percent` or null plus `error`); importable `report_chain_weekly_usage` and `rank_accounts_by_weekly_remaining` (highest remaining first, ties keep config order, unmeasurable last). The chain runner consumes this ranking for try order |
-| `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
-| `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv with no turn cap (the timeout is the only bound), mints a unique leader socket, captures streams, refuses a timeout that is missing, below `MIN_WORKER_TIMEOUT_SECONDS`, or above the `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) ceiling, kills the whole process tree on timeout with grace and retries the kill-and-drain round once, classifies ok/usage_limit/auth_failure/timeout/kill_failed/error; exports `require_timeout_within_bounds` so a dispatcher can apply the same bounds without launching; imported by `spawn_grok_batch.py` and `resolve_worker_spawn.py` |
-| `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |
-| `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
-| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, optionally binds a unique worker advisor per role via the lead-supplied `advisor.launcher` (placeholder default in constants), injects `advisor_session_id`, requires the same session ENDORSE or bounded CORRECTION/PLAN then ENDORSE, classifies bind/verdict/timeout/missing-launcher failures as `advisor_blocked`, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
-| `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
-| `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |
-| `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); applies `require_timeout_within_bounds` before the preflight, so an out-of-bounds `--timeout-seconds` prints a `timeout_out_of_bounds` outcome and exits 3 on every tier; protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
-| `active_capability_references.py` | Inventories committed skill, agent, and command names and scans package markdown for active slash or backticked capability references; fails ban-listed names outside inert historical/example fences |
-| `verify_installable_package.py` | Verifies the published package: runs real `npm pack`, checks every surface in `installable-surfaces.manifest.json` appears in the tarball, requires each `hooks.json` `.py` command to be git-tracked, and smoke-compiles those scripts (`node --check` on `bin/install.mjs`) |
-
-## PowerShell scripts
-
-| File | Purpose |
-|---|---|
-| `Audit-ShellPolicy.ps1` | Audits Bash tool calls in session transcripts against the `pwsh`-only shell policy |
-| `Migrate-ShellPolicy.ps1` | Applies automated fixes for common shell-policy violations found by the audit script |
-| `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
-| `Sync-RepoMain.ps1` | Fast-forwards a main-tracking mirror (`-RepoPath`, required) to its remote main using `merge --ff-only`; refuses a different checkout or a diverged branch, logs each run to `-LogPath`, and exits non-zero so a scheduled-task history row surfaces the problem. `-StashDirty` stashes tracked changes right before the fast-forward under a dated `pre-sync stash` message and leaves the stash in the list |
-| `check.ps1` | Runs the full code-quality check suite |
-| `Get-SessionAccount.ps1` | Reports which Claude account the current session is actually logged into by comparing `~/.claude.json`'s CLI login against a `CLAUDE_USER_DATA_DIR` desktop profile's `lastKnownAccountUuid`, recovering the desktop account's email from profile storage when the two accounts differ |
-| `Capture-PoolHealth.ps1` | Captures Windows memory pool counters, high-handle processes, and kernel pool tags (via `NtQuerySystemInformation` class 22), prints a threshold verdict with a remediation map, and exits non-zero when any alert threshold fires |
-| `Show-Asset.ps1` | Opens files on screen, sizing each image window to the image's pixel dimensions and falling back to the registered default application for non-image files |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `ci/` | CI-only adapters; `windows-installer-lifecycle.ps1` runs the Node installer 16-check driver under isolated HOME/USERPROFILE/GIT_CONFIG_GLOBAL and writes bounded evidence |
-| `dev_env_scripts_constants/` | Named constants (`timing.py`, `grok_worker_constants.py`, …) for scripts in this directory, including worker-advisor placeholder launcher/model/effort, four verdict signals, correction cap, and advisor timeout |
-| `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
-| `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
-
-## Running tests
-
-Python scripts (pytest):
-
-```bash
-python -m pytest packages/claude-dev-env/scripts/tests/
-```
-
-PowerShell scripts (Pester 5+, `*.Tests.ps1`):
-
-```powershell
-Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
-```

package/scripts/dev_env_scripts_constants/AGENTS.md

@@ -1,21 +1 @@
-# dev_env_scripts_constants
 
-Named constants for scripts in `scripts/`. Follows the project convention that timeouts, delays, and retries live in `timing.py`.
-
-## Modules
-
-| File | Constants for |
-|---|---|
-| `timing.py` | `sweep_empty_dirs.py` - `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode); `spawn_grok_batch.py` - `WORKER_STAGGER_SECONDS` (seconds between staggered headless grok worker starts); `invoke_code_review.py` - `DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS` (timeout for one headless `/code-review` chain run) |
-| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
-| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, routing-mode tokens (`usage_ranked` / `ordered_account`), outcome `terminal_status` values (`served` / `advisor_blocked` / `chain_exhausted` / `timeout`), the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes (including advisor-blocked); `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
-| `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
-| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, worker-advisor placeholder launcher/model/effort tokens, four verdict signals, MAXIMUM_WORKER_ADVISOR_CORRECTIONS, advisor_blocked classification, and advisor_session_id report keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
-| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review ultra --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers; finding severity tokens (`blocker` / `high` / `medium` / `low` / `nit`), verification verdict tokens, loop terminal tokens (`clean` / `nits_fixed` / `advisor_blocked`), and pure helpers for retained-finding checks, head recording, terminal resolution, and terminal encoding |
-| `active_capability_constants.py` | `active_capability_references.py` - package skills/agents/commands directory names, skill manifest filename, ban-listed capability names, inert fence languages, slash and backtick extract patterns, fence open/close patterns, banned-reason prefix, UTF-8 encoding, and newline join separator |
-| `verify_installable_package_constants.py` | `verify_installable_package.py` - manifest filename and keys, npm pack / tarball / plugin-root tokens, git and node smoke argv pieces, surface classification labels, exit codes, and CLI status headers |
-| `__init__.py` | Empty package marker |
-
-## Convention
-
-Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies. `code_review_constants.py` also exports pure helpers that resolve review-loop terminals from those tokens.

package/scripts/sync_to_cursor/AGENTS.md

@@ -1,23 +1 @@
-# sync_to_cursor
 
-Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry point is `packages/claude-dev-env/scripts/sync_to_cursor.py`; this package holds the implementation modules.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest; `--claude-root` and `--cursor-root` select explicit layouts |
-| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format; maps remaining `rules/*.md` files to `<stem>.mdc` |
-| `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
-| `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
-| `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
-| `config/` | Package-level constants: `GENERATOR_VERSION`, `ALL_CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES`, skipped inventory filenames, markdown suffix |
-| `__init__.py` | Empty package marker |
-
-## Layout resolution
-
-`paths.py` reads `LLM_SETTINGS_ROOT` from the environment. When set, it uses that path as the base for both `.claude/` and `.cursor/`. When unset, it falls back to `Path.home()`.
-
-## Tests
-
-Tests live in `packages/claude-dev-env/scripts/tests/test_sync_to_cursor.py`.

package/scripts/tests/AGENTS.md

@@ -1,35 +1 @@
-# scripts/tests
 
-pytest suite for the Python scripts and Pester suite for the PowerShell scripts in `scripts/`.
-
-## Test files
-
-| File | Covers |
-|---|---|
-| `test_setup_project_paths.py` | `setup_project_paths.py` — discovery, filtering, and `project-paths.json` writing |
-| `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
-| `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
-| `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
-| `test_rules.py` | Discovered Claude `rules/*.md` mappings to stem-named Cursor `.mdc` files |
-| `test_engine.py` | `sync_to_cursor` engine `--claude-root` / `--cursor-root` layout flags |
-| `test_grok_worker_constants.py` | `grok_worker_constants.py` — the accepted batch worker-key set stays in step with the worker key constants, and the unknown-key message names both its placeholders |
-
-## PowerShell test files
-
-| File | Covers |
-|---|---|
-| `Get-SessionAccount.Tests.ps1` | `Get-SessionAccount.ps1` — noise filtering, profile-storage email recovery, CLI-vs-desktop account resolution, and output formatting |
-
-## Running
-
-Python scripts (pytest):
-
-```bash
-python -m pytest packages/claude-dev-env/scripts/tests/
-```
-
-PowerShell scripts (Pester 5+, `*.Tests.ps1`):
-
-```powershell
-Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
-```

package/system-prompts/AGENTS.md

@@ -1,25 +1 @@
-# system-prompts
 
-System-prompt reference files installed into `~/.claude/system-prompts/` by `bin/install.mjs`. Rules and skills pull a file (or one of its sections) into context on demand by citing its installed path.
-
-Use `~/.claude/rules/asd-ste100-language.md` for user-facing word choice,
-sentence style, tone, punctuation, and prose form. Each prompt keeps its
-role-specific behavior contract.
-
-ELI5 owns the global beginner presentation envelope: large visuals, minimal
-text, one stable self-contained HTML artifact, update-in-place continuity, and
-sharing.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `software-engineer.xml` | Software-engineering reference: defines the engineering role, task-scope rules, output style, and the BDD `<behavior_protocol>` that `rules/bdd.md` cites on demand |
-
-## Format
-
-Files use XML with named sections (`<role>`, `<task_scope>`, `<output_style>`, `<behavior_protocol>`, etc.). A rule or skill cites a file, or one of its sections, to pull it into context when the task needs it.
-
-## Adding a prompt
-
-Create a new `.xml` file and run `bin/install.mjs` to copy it to `~/.claude/system-prompts/`. Reference the new file in the relevant rule or skill by its installed path.