claude-dev-env 2.12.0 → 2.14.0

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/AGENTS.md

@@ -0,0 +1,24 @@
+# skills_pr_loop_constants
+
+Python package of named constants for the `pr-loop` shared scripts. All constants are `UPPER_SNAKE_CASE` module-level names imported by the sibling scripts.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
+| `audit_category_schema_constants.py` | Paths, regexes, and encoding constants for `audit_category_schema.py` (A-Q schema load and projection parity). |
+| `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
+| `handoff_constants.py` | Filename, path-segment, and template constants for the durable handoff writer. |
+| `pacer_constants.py` | Entry-skill names, pacer tokens, CLI flags, and result keys for `select_converge_pacer.py`. |
+| `portable_driver_constants.py` | Phase names, next-action tokens, wait delays, blockers, CLI flags, and result keys for `portable_converge_driver.py`. |
+| `converge_task_list_constants.py` | Task ids, kinds, and CLI flags for `build_converge_task_list.py`. |
+
+## Usage
+
+Scripts import directly from the package:
+
+```python
+from skills_pr_loop_constants.path_resolver_constants import PER_PR_WORKSPACE_TEMPLATE
+```

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/CLAUDE.md

@@ -1,24 +1 @@
-# skills_pr_loop_constants
-
-Python package of named constants for the `pr-loop` shared scripts. All constants are `UPPER_SNAKE_CASE` module-level names imported by the sibling scripts.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `__init__.py` | Package marker. |
-| `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
-| `audit_category_schema_constants.py` | Paths, regexes, and encoding constants for `audit_category_schema.py` (A-Q schema load and projection parity). |
-| `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
-| `handoff_constants.py` | Filename, path-segment, and template constants for the durable handoff writer. |
-| `pacer_constants.py` | Entry-skill names, pacer tokens, CLI flags, and result keys for `select_converge_pacer.py`. |
-| `portable_driver_constants.py` | Phase names, next-action tokens, wait delays, blockers, CLI flags, and result keys for `portable_converge_driver.py`. |
-| `converge_task_list_constants.py` | Task ids, kinds, and CLI flags for `build_converge_task_list.py`. |
-
-## Usage
-
-Scripts import directly from the package:
-
-```python
-from skills_pr_loop_constants.path_resolver_constants import PER_PR_WORKSPACE_TEMPLATE
-```
+@AGENTS.md

package/skills/anthropic-plan/AGENTS.md

@@ -0,0 +1,34 @@
+# anthropic-plan
+
+**Trigger:** `/anthropic-plan`, `/plan`, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial requests that need source-grounded design before build work.
+
+Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The skill first drafts a short starting plan and gets the user's approval in plan mode (`EnterPlanMode` / `ExitPlanMode`); on approval it runs the workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `scripts/` | Python validator (`validate_packet.py`) that checks the packet's required files, placeholders, and consistency. |
+| `templates/` | Template files the workflow renders when building the packet (`README.md`, `build-prompt.md`, `reuse-audit.md`, `source-map.md`, `visual-plan.template.html`). |
+| `workflow/` | The `.mjs` workflow scripts and their test files. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Entry point. Full planning protocol, workflow contract, packet shape, and validation rules. |
+| `workflow/plan-packet.mjs` | Main workflow script. Reads repo context, writes the packet, runs the validator, spawns `plan-packet-validator`, runs the reuse audit, builds the visual HTML, and returns the packet path. |
+| `workflow/plan-packet.contract.test.mjs` | Contract tests for the workflow script. |
+| `packages/claude-dev-env/skills/anthropic-plan/scripts/validate_packet.py` | Deterministic validator: checks required files, open questions, source-map strength, TDD coverage, and `packet.json` consistency. Exits with code 2 on failure. |
+| `templates/visual-plan.template.html` | Template for the single-file offline visual HTML the workflow builds after validation. |
+
+## Entry point
+
+```js
+Workflow({
+  scriptPath: "$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs",
+  args: { task: "<user request>", cwd: "<working directory>" }
+})
+```
+
+The session must be in a worktree (path has `.claude/worktrees/`) before calling the workflow.

package/skills/anthropic-plan/CLAUDE.md

@@ -1,34 +1 @@
-# anthropic-plan
-
-**Trigger:** `/anthropic-plan`, `/plan`, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial requests that need source-grounded design before build work.
-
-Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The skill first drafts a short starting plan and gets the user's approval in plan mode (`EnterPlanMode` / `ExitPlanMode`); on approval it runs the workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `scripts/` | Python validator (`validate_packet.py`) that checks the packet's required files, placeholders, and consistency. |
-| `templates/` | Template files the workflow renders when building the packet (`README.md`, `build-prompt.md`, `reuse-audit.md`, `source-map.md`, `visual-plan.template.html`). |
-| `workflow/` | The `.mjs` workflow scripts and their test files. |
-
-## Key files
-
-| File | Role |
-|---|---|
-| `SKILL.md` | Entry point. Full planning protocol, workflow contract, packet shape, and validation rules. |
-| `workflow/plan-packet.mjs` | Main workflow script. Reads repo context, writes the packet, runs the validator, spawns `plan-packet-validator`, runs the reuse audit, builds the visual HTML, and returns the packet path. |
-| `workflow/plan-packet.contract.test.mjs` | Contract tests for the workflow script. |
-| `packages/claude-dev-env/skills/anthropic-plan/scripts/validate_packet.py` | Deterministic validator: checks required files, open questions, source-map strength, TDD coverage, and `packet.json` consistency. Exits with code 2 on failure. |
-| `templates/visual-plan.template.html` | Template for the single-file offline visual HTML the workflow builds after validation. |
-
-## Entry point
-
-```js
-Workflow({
-  scriptPath: "$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs",
-  args: { task: "<user request>", cwd: "<working directory>" }
-})
-```
-
-The session must be in a worktree (path has `.claude/worktrees/`) before calling the workflow.
+@AGENTS.md

package/skills/anthropic-plan/scripts/AGENTS.md

@@ -0,0 +1,11 @@
+# scripts
+
+Python scripts for the `anthropic-plan` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `validate_packet.py` | Deterministic packet validator. Checks that all required files exist under `docs/plans/<slug>/`, that no placeholder text remains, that `packet.json` is consistent with the folder contents, and that the TDD plan is present. Exits with code 2 on failure; the workflow treats a non-zero exit as a blocking finding. |
+| `test_validate_packet.py` | Tests for `validate_packet.py`. |
+| `anthropic_plan_scripts_constants/` | Named constants package (`validate_packet_constants.py`) that lists every required relative path the validator checks. |

package/skills/anthropic-plan/scripts/CLAUDE.md

@@ -1,11 +1 @@
-# scripts
-
-Python scripts for the `anthropic-plan` skill.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `validate_packet.py` | Deterministic packet validator. Checks that all required files exist under `docs/plans/<slug>/`, that no placeholder text remains, that `packet.json` is consistent with the folder contents, and that the TDD plan is present. Exits with code 2 on failure; the workflow treats a non-zero exit as a blocking finding. |
-| `test_validate_packet.py` | Tests for `validate_packet.py`. |
-| `anthropic_plan_scripts_constants/` | Named constants package (`validate_packet_constants.py`) that lists every required relative path the validator checks. |
+@AGENTS.md

package/skills/anthropic-plan/scripts/anthropic_plan_scripts_constants/AGENTS.md

@@ -0,0 +1,16 @@
+# anthropic_plan_scripts_constants
+
+Python package of named constants for `anthropic-plan/scripts/`.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `validate_packet_constants.py` | Defines `ALL_REQUIRED_RELATIVE_PATHS` — the tuple of every relative path that must exist inside a valid plan packet (e.g. `README.md`, `packet.json`, `context/source-map.md`, `implementation/tdd-plan.md`, `handoff/build-prompt.md`). Also defines `MARKDOWN_FILE_SUFFIX` and `EXIT_CODE_VALIDATION_FAILED`. |
+
+## Usage
+
+```python
+from anthropic_plan_scripts_constants.validate_packet_constants import ALL_REQUIRED_RELATIVE_PATHS
+```

package/skills/anthropic-plan/scripts/anthropic_plan_scripts_constants/CLAUDE.md

@@ -1,16 +1 @@
-# anthropic_plan_scripts_constants
-
-Python package of named constants for `anthropic-plan/scripts/`.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `__init__.py` | Package marker. |
-| `validate_packet_constants.py` | Defines `ALL_REQUIRED_RELATIVE_PATHS` — the tuple of every relative path that must exist inside a valid plan packet (e.g. `README.md`, `packet.json`, `context/source-map.md`, `implementation/tdd-plan.md`, `handoff/build-prompt.md`). Also defines `MARKDOWN_FILE_SUFFIX` and `EXIT_CODE_VALIDATION_FAILED`. |
-
-## Usage
-
-```python
-from anthropic_plan_scripts_constants.validate_packet_constants import ALL_REQUIRED_RELATIVE_PATHS
-```
+@AGENTS.md

package/skills/anthropic-plan/templates/AGENTS.md

@@ -0,0 +1,13 @@
+# templates
+
+Template files the `plan-packet.mjs` workflow renders when building a plan packet.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `README.md` | Markdown template for the packet's top-level `README.md`. Placeholder slots for plan title, goal, status, packet map, and build path. |
+| `build-prompt.md` | Template for `handoff/build-prompt.md` — the standalone prompt the build agent reads to start coding without needing the rest of the packet. |
+| `reuse-audit.md` | Template for `validation/reuse-audit.md` — the per-item verdict table the workflow fills in during the reuse audit step. |
+| `source-map.md` | Template for `context/source-map.md` — the inventory of source files and facts the planner extracts. |
+| `visual-plan.template.html` | Single-file offline HTML template. The workflow fills this with packet data after validation to produce `visual-plan.html` beside the packet. Inlines all CSS and JavaScript; references no external assets. |

package/skills/anthropic-plan/templates/CLAUDE.md

@@ -1,13 +1 @@
-# templates
-
-Template files the `plan-packet.mjs` workflow renders when building a plan packet.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `README.md` | Markdown template for the packet's top-level `README.md`. Placeholder slots for plan title, goal, status, packet map, and build path. |
-| `build-prompt.md` | Template for `handoff/build-prompt.md` — the standalone prompt the build agent reads to start coding without needing the rest of the packet. |
-| `reuse-audit.md` | Template for `validation/reuse-audit.md` — the per-item verdict table the workflow fills in during the reuse audit step. |
-| `source-map.md` | Template for `context/source-map.md` — the inventory of source files and facts the planner extracts. |
-| `visual-plan.template.html` | Single-file offline HTML template. The workflow fills this with packet data after validation to produce `visual-plan.html` beside the packet. Inlines all CSS and JavaScript; references no external assets. |
+@AGENTS.md

package/skills/anthropic-plan/workflow/AGENTS.md

@@ -0,0 +1,14 @@
+# workflow
+
+Workflow scripts for the `anthropic-plan` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `plan-packet.mjs` | Main workflow script. Resolves repo root, reads project context, builds the source inventory, writes the full packet under `docs/plans/<slug>/`, runs `validate_packet.py`, spawns `plan-packet-validator` in a fresh context, runs the reuse audit, builds the visual HTML from `templates/visual-plan.template.html`, and returns the packet path and validation state. |
+| `plan-packet.contract.test.mjs` | Contract tests that verify the workflow script's interface and required steps without a live repo. |
+
+## Running
+
+The `plan-packet.mjs` script runs via the `Workflow` tool — do not invoke it directly with Node. The skill's `SKILL.md` specifies the exact call signature and required `args`.

package/skills/anthropic-plan/workflow/CLAUDE.md

@@ -1,14 +1 @@
-# workflow
-
-Workflow scripts for the `anthropic-plan` skill.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `plan-packet.mjs` | Main workflow script. Resolves repo root, reads project context, builds the source inventory, writes the full packet under `docs/plans/<slug>/`, runs `validate_packet.py`, spawns `plan-packet-validator` in a fresh context, runs the reuse audit, builds the visual HTML from `templates/visual-plan.template.html`, and returns the packet path and validation state. |
-| `plan-packet.contract.test.mjs` | Contract tests that verify the workflow script's interface and required steps without a live repo. |
-
-## Running
-
-The `plan-packet.mjs` script runs via the `Workflow` tool — do not invoke it directly with Node. The skill's `SKILL.md` specifies the exact call signature and required `args`.
+@AGENTS.md

package/skills/auditing-claude-config/AGENTS.md

@@ -0,0 +1,21 @@
+# auditing-claude-config
+
+**Trigger:** `/auditing-claude-config`, reviewing the startup instruction load, `/memory` showing unexpected files, adding new rules, periodic config hygiene.
+
+Audits a Claude Code setup — user `CLAUDE.md`, `~/.claude/rules/`, project `.claude/` — for context-budget waste: duplicate `@`-imports, always-on rules that could be path-scoped or turned into skills, and oversized files. Produces a migration table with line savings.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Full audit protocol: inventory the always-loaded set, find duplicate imports, classify each rule, produce the migration table, stage recommendations by risk, and verify lazy-load behavior with an optional probe hook. |
+| `reference/probe-hook.md` | The optional lazy-load probe hook: hook script, `settings.json` registration, and test protocol. |
+
+## What the skill produces
+
+1. **Baseline** — total always-loaded lines, broken down by file.
+2. **Migration table** — one row per rule: current lines, verdict, specific action, lines removed from preload.
+3. **Recommended next step** — the single highest-leverage change.
+4. **Open questions** — anything not verified by the probe hook.
+
+No runnable scripts or workflow files. The audit logic lives in the skill body; the optional lazy-load probe hook lives in `reference/probe-hook.md` as copy-ready text.

package/skills/auditing-claude-config/CLAUDE.md

@@ -1,21 +1 @@
-# auditing-claude-config
-
-**Trigger:** `/auditing-claude-config`, reviewing the startup instruction load, `/memory` showing unexpected files, adding new rules, periodic config hygiene.
-
-Audits a Claude Code setup — user `CLAUDE.md`, `~/.claude/rules/`, project `.claude/` — for context-budget waste: duplicate `@`-imports, always-on rules that could be path-scoped or turned into skills, and oversized files. Produces a migration table with line savings.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `SKILL.md` | Full audit protocol: inventory the always-loaded set, find duplicate imports, classify each rule, produce the migration table, stage recommendations by risk, and verify lazy-load behavior with an optional probe hook. |
-| `reference/probe-hook.md` | The optional lazy-load probe hook: hook script, `settings.json` registration, and test protocol. |
-
-## What the skill produces
-
-1. **Baseline** — total always-loaded lines, broken down by file.
-2. **Migration table** — one row per rule: current lines, verdict, specific action, lines removed from preload.
-3. **Recommended next step** — the single highest-leverage change.
-4. **Open questions** — anything not verified by the probe hook.
-
-No runnable scripts or workflow files. The audit logic lives in the skill body; the optional lazy-load probe hook lives in `reference/probe-hook.md` as copy-ready text.
+@AGENTS.md

package/skills/autoconverge/AGENTS.md

@@ -0,0 +1,36 @@
+# autoconverge
+
+**Trigger:** `/autoconverge`, "autoconverge this PR", "converge this PR in one run", "run the converge workflow", "drive the PR to ready autonomously".
+
+Drives one draft PR to convergence in one autonomous run. On `pacer=workflow`, each round runs a deterministic static sweep first, then a code-review pass, a bug-audit (with its adversarial second pass), and a self-review parity pass in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, and re-verifies; state lives in the workflow journal. On `pacer=portable`, the continuous driver in `_shared/pr-loop/portable-driver.md` runs the shared pr-converge phase machine with the same helpers and `check_convergence.py` ready definition. Once the internal passes are clean, Cursor Bugbot, Copilot, and Codex run as terminal confirmation gates, and the run marks the PR ready on convergence.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Markdown docs the skill and workflow cite: round shape, stop conditions, gotchas, and closing report format. |
+| `workflow/` | The `.mjs` convergence workflow, Python report scripts, test files, and the `autoconverge_report_constants/` package. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Full entry-point protocol: pacer selection, pre-flight steps, worktree setup, Workflow or portable path, budget-aware boundaries, teardown, and the convergence loop summary. |
+| `workflow/converge.mjs` | Main convergence workflow. Runs a static sweep then the internal lenses each round, applies fixes, runs Bugbot, Copilot, and Codex as terminal gates, checks convergence, and marks the PR ready. |
+| `workflow/aggregate_runs.py` | Merges every autoconverge journal for a PR into one deduped journal. |
+| `workflow/convergence_summary.py` | Builds the convergence-summary agent prompt over the merged findings. |
+| `workflow/render_report.py` | Builds the closing HTML report from the merged journal and summary. |
+| `reference/convergence.md` | Round shape: the static sweep, the three parallel internal lenses, deduplication, fix commit, the terminal Bugbot, Copilot, and Codex gates, and the ready definition. |
+| `reference/copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
+| `reference/stop-conditions.md` | Every way the run ends short of ready, including the budget stop. |
+| `reference/gotchas.md` | Hard-won failure lessons. |
+| `reference/closing-report.md` | The closing HTML report: data source, build steps, publishing. |
+| `reference/multi-pr.md` | The several-PRs path: per-PR worktrees, the `converge_multi.mjs` launch, per-PR teardown. |
+| `reference/self-closing-loop.md` | The deferred-PR generations and the Conventional-Commit title rule. |
+| `reference/headless-safety.md` | The agent-prompt headless-safety preamble and the rm auto-allow paths. |
+
+## Entry point
+
+Selects `workflow` or `portable` via `select_converge_pacer.py`. Missing
+`Workflow` selects portable and continues — it does not abort. The `SKILL.md`
+body specifies the pre-flight sequence and each pacer's run path.

package/skills/autoconverge/CLAUDE.md

@@ -1,36 +1 @@
-# autoconverge
-
-**Trigger:** `/autoconverge`, "autoconverge this PR", "converge this PR in one run", "run the converge workflow", "drive the PR to ready autonomously".
-
-Drives one draft PR to convergence in one autonomous run. On `pacer=workflow`, each round runs a deterministic static sweep first, then a code-review pass, a bug-audit (with its adversarial second pass), and a self-review parity pass in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, and re-verifies; state lives in the workflow journal. On `pacer=portable`, the continuous driver in `_shared/pr-loop/portable-driver.md` runs the shared pr-converge phase machine with the same helpers and `check_convergence.py` ready definition. Once the internal passes are clean, Cursor Bugbot, Copilot, and Codex run as terminal confirmation gates, and the run marks the PR ready on convergence.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `reference/` | Markdown docs the skill and workflow cite: round shape, stop conditions, gotchas, and closing report format. |
-| `workflow/` | The `.mjs` convergence workflow, Python report scripts, test files, and the `autoconverge_report_constants/` package. |
-
-## Key files
-
-| File | Role |
-|---|---|
-| `SKILL.md` | Full entry-point protocol: pacer selection, pre-flight steps, worktree setup, Workflow or portable path, budget-aware boundaries, teardown, and the convergence loop summary. |
-| `workflow/converge.mjs` | Main convergence workflow. Runs a static sweep then the internal lenses each round, applies fixes, runs Bugbot, Copilot, and Codex as terminal gates, checks convergence, and marks the PR ready. |
-| `workflow/aggregate_runs.py` | Merges every autoconverge journal for a PR into one deduped journal. |
-| `workflow/convergence_summary.py` | Builds the convergence-summary agent prompt over the merged findings. |
-| `workflow/render_report.py` | Builds the closing HTML report from the merged journal and summary. |
-| `reference/convergence.md` | Round shape: the static sweep, the three parallel internal lenses, deduplication, fix commit, the terminal Bugbot, Copilot, and Codex gates, and the ready definition. |
-| `reference/copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
-| `reference/stop-conditions.md` | Every way the run ends short of ready, including the budget stop. |
-| `reference/gotchas.md` | Hard-won failure lessons. |
-| `reference/closing-report.md` | The closing HTML report: data source, build steps, publishing. |
-| `reference/multi-pr.md` | The several-PRs path: per-PR worktrees, the `converge_multi.mjs` launch, per-PR teardown. |
-| `reference/self-closing-loop.md` | The deferred-PR generations and the Conventional-Commit title rule. |
-| `reference/headless-safety.md` | The agent-prompt headless-safety preamble and the rm auto-allow paths. |
-
-## Entry point
-
-Selects `workflow` or `portable` via `select_converge_pacer.py`. Missing
-`Workflow` selects portable and continues — it does not abort. The `SKILL.md`
-body specifies the pre-flight sequence and each pacer's run path.
+@AGENTS.md

package/skills/autoconverge/reference/AGENTS.md

@@ -0,0 +1,16 @@
+# reference
+
+Reference documentation for the `autoconverge` skill. The `converge.mjs` workflow and the `SKILL.md` cite these files to define behavior precisely.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `convergence.md` | Round shape: the static sweep, the three parallel internal lenses (code-review, bug-audit, self-review), deduplication, the fix commit step, the terminal Bugbot, Copilot, and Codex gates, and the definition of a clean convergence. |
+| `copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
+| `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, static-sweep stall, Bugbot, Copilot, and Codex bypass. |
+| `gotchas.md` | Current operating guidance for PR title validation, conflicting PRs, worktree branch lock, resumed sessions, and commit or push failures. |
+| `closing-report.md` | The closing HTML convergence report the teardown step builds and publishes: data source, build steps, publishing. |
+| `multi-pr.md` | The several-PRs path: per-PR worktrees, the `converge_multi.mjs` launch, per-PR teardown. |
+| `self-closing-loop.md` | The deferred-PR generations the orchestrator converges after teardown, and the Conventional-Commit title rule on hardening PRs. |
+| `headless-safety.md` | The headless-safety preamble every agent prompt carries, and the rm auto-allow paths. |

package/skills/autoconverge/reference/CLAUDE.md

@@ -1,16 +1 @@
-# reference
-
-Reference documentation for the `autoconverge` skill. The `converge.mjs` workflow and the `SKILL.md` cite these files to define behavior precisely.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `convergence.md` | Round shape: the static sweep, the three parallel internal lenses (code-review, bug-audit, self-review), deduplication, the fix commit step, the terminal Bugbot, Copilot, and Codex gates, and the definition of a clean convergence. |
-| `copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
-| `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, static-sweep stall, Bugbot, Copilot, and Codex bypass. |
-| `gotchas.md` | Hard-won lessons from failed runs: PR title validation, conflicting PRs, worktree branch lock, resumed sessions rerooting, and minter issues. |
-| `closing-report.md` | The closing HTML convergence report the teardown step builds and publishes: data source, build steps, publishing. |
-| `multi-pr.md` | The several-PRs path: per-PR worktrees, the `converge_multi.mjs` launch, per-PR teardown. |
-| `self-closing-loop.md` | The deferred-PR generations the orchestrator converges after teardown, and the Conventional-Commit title rule on hardening PRs. |
-| `headless-safety.md` | The headless-safety preamble every agent prompt carries, and the rm auto-allow paths. |
+@AGENTS.md

package/skills/autoconverge/reference/convergence.md

@@ -5,9 +5,9 @@
 Before the first round, the workflow checks once whether the PR branch conflicts
 with `origin/main`. When GitHub reports a conflict (`mergeable` false or
 `mergeable_state` dirty), one `clean-coder` rebases the branch onto `origin/main`
-and resolves every conflict — gated the same way as every other code change: the
-edit leaves the rebase in the working tree, a `code-verifier` binds a verdict to
-it, and the commit step force-pushes with lease. The bug checks then run on a
+and resolves every conflict — the edit remains in the working tree, review and
+verification follow the [review guide](../../reviews/SKILL.md#review-workflow),
+and the commit step force-pushes with lease. The bug checks then run on a
 conflict-free diff.
 
 A PR that merges cleanly skips the rebase. A conflict that surfaces mid-run, when
@@ -61,8 +61,8 @@ confirmation gates that are expected to return zero.
    the round re-runs, so the reading lenses only ever review sweep-clean code.
 3. Run three reading lenses in parallel on that HEAD, each over the full
    `origin/main...HEAD` diff. Each lens receives the preflight's changed-file
-   list and diffstat and reads only the files it needs from that list rather than
-   re-deriving the diff; each lens forms its own review judgment.
+list and diffstat and reads only the files it needs from that list rather than
+re-deriving the diff; each lens applies the [review guide](../../reviews/SKILL.md#review-judgment).
    - **Code-review lens** — a correctness-focused review pass (`code-quality-agent`),
      report-only workflow agent — see runCodeReviewLens in workflow/converge.mjs for its configuration.
      The built-in `/code-review` command is a separate surface outside this
@@ -113,8 +113,8 @@ When the already-deduped findings for a phase are all severity P2 (and not
 standards-only), the phase still applies the fixes once. If the fix does **not**
 move HEAD (for example `resolvedWithoutCommit`), the phase treats that HEAD as
 clean and advances forward. If the fix **does** move HEAD, the run re-enters
-CONVERGE on the fixed SHA so HEAD-bound CLEAN/review stamps rebuild before
-FINALIZE — those stamps are SHA-specific. The three CONVERGE reading lenses stay
+CONVERGE on the fixed SHA so the current review state rebuilds before
+FINALIZE. The three CONVERGE reading lenses stay
 parallel; the P2-only decision is a routing branch on the deduped set after
 `resolveRoundOutcome` / gate classification. Mixed P0/P1 findings keep the
 existing fix + re-converge path.

package/skills/autoconverge/reference/gotchas.md

@@ -50,16 +50,9 @@ fails in a new way.
   account, pin the token with `--user <login>`; `gh auth token` alone can return
   another account's token after a switch.
 
-- **The verified-commit gate can block the fix from landing.** The fix lens
-  commits and pushes through the `verified_commit_gate` hook, which denies a
-  `git commit`/`git push` until a `code-verifier` verdict covers the branch
-  surface. A run can reach a clean fix yet fail to land it — the push stays
-  blocked when no verdict is minted for that surface. A manual override exists:
-  a trailing `# verify-skip` comment on the commit or push command skips the
-  gate for that one command. Autoconverge must never apply that override on its
-  own. When landing a fix needs it, stop and tell the user the verified-commit
-  gate is blocking the push and that going forward needs either a `# verify-skip`
-  bypass or a switch to `/pr-converge`, then let the user decide.
+- **Commit or push fails after a repair.** Read the hook or command output,
+  repair the named issue, and record the rerun. Apply the
+  [review guide](../../reviews/SKILL.md#review-workflow) before retrying.
 
 - **A Copilot "down" verdict is valid only after the full poll budget.** A
   successful review request means the review is in flight — Copilot typically

package/skills/autoconverge/workflow/AGENTS.md

@@ -0,0 +1,26 @@
+# workflow
+
+Workflow scripts and report utilities for the `autoconverge` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `converge.mjs` | Main convergence workflow script. Each round runs a deterministic static sweep first, then code-review, bug-audit, and self-review lenses in parallel, deduplicates findings, applies fixes, and pushes; Bugbot, Copilot, and Codex then run as terminal confirmation gates before it checks convergence and marks the PR ready. Runs via the `Workflow` tool — not directly with Node. |
+| `aggregate_runs.py` | Merges every autoconverge journal for a given PR (matched by run id) into one merged journal. Prints a JSON line with `mergedJournal`, `roundCount`, `finalSha`, and `findingCount`. |
+| `convergence_summary.py` | Builds the convergence-summary agent prompt over the merged journal's findings. The teardown step spawns a `general-purpose` subagent on this prompt. |
+| `render_report.py` | Builds the closing HTML insights report. Takes `--journal`, `--summary-file`, `--out`, `--pr`, `--final-sha`, and `--rounds`. Writes the HTML to `--out` and prints the output path on stdout. |
+| `autoconverge_report_constants/` | Named constants package for `render_report.py` and `convergence_summary.py`. |
+| `converge.contract.test.mjs` | Contract tests for `converge.mjs` — verify the workflow interface and step ordering. |
+| `converge.clean-audit.test.mjs` | Tests the clean-audit path (all lenses clean on first round). |
+| `converge.copilot-gate.test.mjs` | Tests Copilot gate behavior (bypass on quota exhaustion). |
+| `converge.codex-gate.test.mjs` | Tests Codex gate classification (required+clean, skip-token, skip-usage, codex_down) and phase wiring. |
+| `converge.precatch.test.mjs` | Tests the pre-catch stage: static-sweep ordering and gate coverage, the adversarial second pass, the self-review lens, the terminal Bugbot gate, the read-only/edit preamble split, and the commit-recovery cap. |
+| `converge.fix-progress.test.mjs` | Tests fix-progress tracking across rounds. |
+| `converge.fix-recovery.test.mjs` | Tests recovery when a fix commit fails. |
+| `converge.p2-advance.test.mjs` | Tests P2-only fix-then-advance helpers and phase routing. |
+| `converge.run-input.test.mjs` | Tests workflow input validation. |
+| `test_aggregate_runs.py` | Tests for `aggregate_runs.py`. |
+| `test_convergence_summary.py` | Tests for `convergence_summary.py`. |
+| `test_render_report.py` | Tests for `render_report.py`. |
+| `fixtures/` | Test fixture data for the workflow tests. |

package/skills/autoconverge/workflow/CLAUDE.md

@@ -1,26 +1 @@
-# workflow
-
-Workflow scripts and report utilities for the `autoconverge` skill.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `converge.mjs` | Main convergence workflow script. Each round runs a deterministic static sweep first, then code-review, bug-audit, and self-review lenses in parallel, deduplicates findings, applies fixes, and pushes; Bugbot, Copilot, and Codex then run as terminal confirmation gates before it checks convergence and marks the PR ready. Runs via the `Workflow` tool — not directly with Node. |
-| `aggregate_runs.py` | Merges every autoconverge journal for a given PR (matched by run id) into one merged journal. Prints a JSON line with `mergedJournal`, `roundCount`, `finalSha`, and `findingCount`. |
-| `convergence_summary.py` | Builds the convergence-summary agent prompt over the merged journal's findings. The teardown step spawns a `general-purpose` subagent on this prompt. |
-| `render_report.py` | Builds the closing HTML insights report. Takes `--journal`, `--summary-file`, `--out`, `--pr`, `--final-sha`, and `--rounds`. Writes the HTML to `--out` and prints the output path on stdout. |
-| `autoconverge_report_constants/` | Named constants package for `render_report.py` and `convergence_summary.py`. |
-| `converge.contract.test.mjs` | Contract tests for `converge.mjs` — verify the workflow interface and step ordering. |
-| `converge.clean-audit.test.mjs` | Tests the clean-audit path (all lenses clean on first round). |
-| `converge.copilot-gate.test.mjs` | Tests Copilot gate behavior (bypass on quota exhaustion). |
-| `converge.codex-gate.test.mjs` | Tests Codex gate classification (required+clean, skip-token, skip-usage, codex_down) and phase wiring. |
-| `converge.precatch.test.mjs` | Tests the pre-catch stage: static-sweep ordering and gate coverage, the adversarial second pass, the self-review lens, the terminal Bugbot gate, the read-only/edit preamble split, and the commit-recovery cap. |
-| `converge.fix-progress.test.mjs` | Tests fix-progress tracking across rounds. |
-| `converge.fix-recovery.test.mjs` | Tests recovery when a fix commit fails. |
-| `converge.p2-advance.test.mjs` | Tests P2-only fix-then-advance helpers and phase routing. |
-| `converge.run-input.test.mjs` | Tests workflow input validation. |
-| `test_aggregate_runs.py` | Tests for `aggregate_runs.py`. |
-| `test_convergence_summary.py` | Tests for `convergence_summary.py`. |
-| `test_render_report.py` | Tests for `render_report.py`. |
-| `fixtures/` | Test fixture data for the workflow tests. |
+@AGENTS.md

package/skills/autoconverge/workflow/autoconverge_report_constants/AGENTS.md

@@ -0,0 +1,16 @@
+# autoconverge_report_constants
+
+Python package of named constants for `render_report.py` and `convergence_summary.py` in the `autoconverge/workflow/` directory.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `render_report_constants.py` | Named constants for the report renderer: structured output tool name, journal label prefixes (`resolve-head`, `lens:`, `fix:`, `copilot-gate`, `convergence-summary`), journal sibling directory names, default finding category and severity, date and SHA length constants, workflow name, projects directory name, merged run id prefix, summary detail character limit, and `onexc` Python version threshold. |
+
+## Usage
+
+```python
+from autoconverge_report_constants.render_report_constants import LABEL_PREFIX_LENS
+```

package/skills/autoconverge/workflow/autoconverge_report_constants/CLAUDE.md

@@ -1,16 +1 @@
-# autoconverge_report_constants
-
-Python package of named constants for `render_report.py` and `convergence_summary.py` in the `autoconverge/workflow/` directory.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `__init__.py` | Package marker. |
-| `render_report_constants.py` | Named constants for the report renderer: structured output tool name, journal label prefixes (`resolve-head`, `lens:`, `fix:`, `copilot-gate`, `convergence-summary`), journal sibling directory names, default finding category and severity, date and SHA length constants, workflow name, projects directory name, merged run id prefix, summary detail character limit, and `onexc` Python version threshold. |
-
-## Usage
-
-```python
-from autoconverge_report_constants.render_report_constants import LABEL_PREFIX_LENS
-```
+@AGENTS.md