claude-dev-env 2.4.0 → 2.7.0

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

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

package/skills/pr-converge/test_step5_host_branch.py

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

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

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

package/skills/privacy-hygiene/SKILL.md

@@ -1,68 +1,68 @@
----
-name: privacy-hygiene
-description: Full-repo sweep for personal data and secrets before commit or durable GitHub post. Use when preparing a PR, cleaning a leak, or when `pii_prevention_blocker` denies a write, post, or commit. Triggers on "privacy hygiene", "personal data", "secret sweep", "sanitize repository", "/privacy-hygiene".
----
-
-# privacy-hygiene
-
-## Overview
-
-Find and remove personal data and high-confidence secrets before they land in git history or a durable GitHub post. The `pii_prevention_blocker` hook blocks the common cases at write, post, and commit time. This skill is the full sweep when you need a broader pass or a remediation plan.
-
-**Announce at start:** "Running privacy-hygiene sweep."
-
-## When to run a full sweep
-
-- Before the first push of a branch that touched logs, screenshots, config samples, or machine-local paths
-- After a hook block on email, home path, LAN address, or secret material
-- Before opening a PR to a repository that is public (or will be made public)
-- After pasting support tickets, env dumps, or terminal transcripts into the tree
-
-## What the automated gate blocks
-
-| Category | Blocked examples | Allowed residual |
-|---|---|---|
-| Email | `user@example.com` | `user@example.com`, `user@example.org`, `user@example.net` |
-| Home path | `C:/Users/example/...`, `/Users/example/...`, `/home/example/...` | `C:/Users/example/...`, `C:/Users/<you>/...`, `/Users/alice/...` |
-| LAN address | Unlisted `10.x` / `172.16–31.x` / `192.168.x` | Public addresses; your NAS host from `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`; entries in `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` |
-| Secret | `ghp_…`, `github_pat_…`, `AKIA…`, PEM private-key headers | Public keys, redacted `***`, env var names without values |
-
-Surfaces:
-
-1. **Write / Edit / MultiEdit** — payload text about to land on disk (via PreToolUse dispatcher)
-2. **Durable posts** — `gh pr/issue create|comment|edit|review` bodies and GitHub MCP body/comment fields (Bash and PowerShell)
-3. **git commit** — staged blob text (non-exempt paths) on Bash and PowerShell, including `git.exe` and flag forms (`--no-verify`, `-c`, `-C`). Commit message bodies (`-m` / `-F`) are out of scope for the automated gate
-
-## Sweep procedure
-
-Run the full-tree sweep in
-[`reference/sweep-procedure.md`](reference/sweep-procedure.md): scope the tree,
-run the ripgrep pass for the four high-confidence pattern families (email, home
-path, LAN address, secret), review each hit against the ignore list, and
-remediate. It also lists the accepted residual — what to leave in place rather
-than over-scrub. The ripgrep command is the only full-tree pass; the write-time
-`pii_prevention_blocker` scans one payload at a time.
-
-## Enable on any machine / public repository
-
-Install or reinstall the package so hooks and this skill land under `~/.claude/`:
-
-```
-cd packages/claude-dev-env
-node bin/install.mjs
-```
-
-Hooks register via `hooks/hooks.json` into `~/.claude/settings.json`. Once installed, the same gates apply in every repository the agent touches — private or public.
-
-## Open knobs
-
-- **NAS / LAN allowlist:** Unlisted private IPs are blocked. The scanner resolves your NAS host from `CLAUDE_NAS_HOST`, then `~/.claude/local-identity.json` (`nas.host`), and allowlists it when it is a private address, so the committed tree holds no real host. `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` in `hooks_constants` holds the static allowlist for any host every machine must share.
-- **Commit-scan exempt repositories:** named owner/repo slugs skip the staged-commit PII scan only. Set `CLAUDE_PII_EXEMPT_REPOS` (comma-separated `owner/repo` values) or list them under `pii_exempt_repositories` in `~/.claude/local-identity.json`. Matching uses the repository's `remote.origin.url` and accepts only the exact host `github.com` (https, ssh scheme, or scp-style). A repository with no readable origin is never exempt (fail-closed to scanning). Write / Edit / MultiEdit and durable post bodies still scan in every repository.
-- **Public maintainer identity:** when a real email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
-
-## What this skill does not do
-
-- Does not rewrite git history without explicit user approval
-- Does not rotate credentials for you
-- Does not replace the write-time hook — it complements it
-- Does not scan commit-message text (`-m` / `-F`); keep messages free of secrets yourself
+---
+name: privacy-hygiene
+description: Full-repo sweep for personal data and secrets before commit or durable GitHub post. Use when preparing a PR, cleaning a leak, or when `pii_prevention_blocker` denies a write, post, or commit. Triggers on "privacy hygiene", "personal data", "secret sweep", "sanitize repository", "/privacy-hygiene".
+---
+
+# privacy-hygiene
+
+## Overview
+
+Find and remove personal data and high-confidence secrets before they land in git history or a durable GitHub post. The `pii_prevention_blocker` hook blocks the common cases at write, post, and commit time. This skill is the full sweep when you need a broader pass or a remediation plan.
+
+**Announce at start:** "Running privacy-hygiene sweep."
+
+## When to run a full sweep
+
+- Before the first push of a branch that touched logs, screenshots, config samples, or machine-local paths
+- After a hook block on email, home path, LAN address, or secret material
+- Before opening a PR to a repository that is public (or will be made public)
+- After pasting support tickets, env dumps, or terminal transcripts into the tree
+
+## What the automated gate blocks
+
+| Category | Blocked examples | Allowed residual |
+|---|---|---|
+| Email | `user@example.com` | `user@example.com`, `user@example.org`, `user@example.net` |
+| Home path | `C:/Users/example/...`, `/Users/example/...`, `/home/example/...` | `C:/Users/example/...`, `C:/Users/<you>/...`, `/Users/alice/...` |
+| LAN address | Unlisted `10.x` / `172.16–31.x` / `192.168.x` | Public addresses; your NAS host from `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`; entries in `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` |
+| Secret | `ghp_…`, `github_pat_…`, `AKIA…`, PEM private-key headers | Public keys, redacted `***`, env var names without values |
+
+Surfaces:
+
+1. **Write / Edit / MultiEdit** — payload text about to land on disk (via PreToolUse dispatcher)
+2. **Durable posts** — `gh pr/issue create|comment|edit|review` bodies and GitHub MCP body/comment fields (Bash and PowerShell)
+3. **git commit** — staged blob text (non-exempt paths) on Bash and PowerShell, including `git.exe` and flag forms (`--no-verify`, `-c`, `-C`). Commit message bodies (`-m` / `-F`) are out of scope for the automated gate
+
+## Sweep procedure
+
+Run the full-tree sweep in
+[`reference/sweep-procedure.md`](reference/sweep-procedure.md): scope the tree,
+run the ripgrep pass for the four high-confidence pattern families (email, home
+path, LAN address, secret), review each hit against the ignore list, and
+remediate. It also lists the accepted residual — what to leave in place rather
+than over-scrub. The ripgrep command is the only full-tree pass; the write-time
+`pii_prevention_blocker` scans one payload at a time.
+
+## Enable on any machine / public repository
+
+Install or reinstall the package so hooks and this skill land under `~/.claude/`:
+
+```
+cd packages/claude-dev-env
+node bin/install.mjs
+```
+
+Hooks register via `hooks/hooks.json` into `~/.claude/settings.json`. Once installed, the same gates apply in every repository the agent touches — private or public.
+
+## Open knobs
+
+- **NAS / LAN allowlist:** Unlisted private IPs are blocked. The scanner resolves your NAS host from `CLAUDE_NAS_HOST`, then `~/.claude/local-identity.json` (`nas.host`), and allowlists it when it is a private address, so the committed tree holds no real host. `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` in `hooks_constants` holds the static allowlist for any host every machine must share.
+- **Commit-scan exempt repositories:** named owner/repo slugs skip the staged-commit PII scan only. Set `CLAUDE_PII_EXEMPT_REPOS` (comma-separated `owner/repo` values) or list them under `pii_exempt_repositories` in `~/.claude/local-identity.json`. Matching uses the repository's `remote.origin.url` and accepts only the exact host `github.com` (https, ssh scheme, or scp-style). A repository with no readable origin is never exempt (fail-closed to scanning). Write / Edit / MultiEdit and durable post bodies still scan in every repository.
+- **Public maintainer identity:** when a real email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
+
+## What this skill does not do
+
+- Does not rewrite git history without explicit user approval
+- Does not rotate credentials for you
+- Does not replace the write-time hook — it complements it
+- Does not scan commit-message text (`-m` / `-F`); keep messages free of secrets yourself

package/skills/privacy-hygiene/reference/sweep-procedure.md

@@ -49,7 +49,7 @@ Review each hit. Ignore:
 ## 4. Re-check before commit / post
 
 - Stage only clean files
-- Prefer `--body-file` for `gh` posts (also required by the gh-body-file rule)
+- Prefer `--body-file` for `gh` posts (also required by the gh-cli-conventions rule)
 - Let `pii_prevention_blocker` re-run on the next Write / commit / post
 
 ## Accepted residual (do not over-scrub)

package/skills/prototype/workflows/promotion.md

@@ -15,7 +15,7 @@ The task seeds carry the full ordered detail. The shape:
 3. **Bring content as an uncommitted diff.** Copy the POC's file changes into the new branch's working tree. Do not cherry-pick or merge the sandbox commits; the sandbox history stays behind.
 4. **Cleanup.** Remove scratch files, debug dumps, and temp helpers the POC created (`cleanup-temp-files` rule).
 5. **Privacy sweep** via `privacy-hygiene` over the diff.
-6. **Verify** with the `code-verifier` agent in a fresh context. This is where standards re-engage. Expect findings and a repair loop — the POC was un-TDD'd.
+6. **Verify** with the `code-verifier` agent — `model: sonnet`, worker-model routing per [`skills/orchestrator/SKILL.md`](../../orchestrator/SKILL.md#workflow-agent-routing); resolver-supplied sonnet-equivalent on third-party hosts — in a fresh context. This is where standards re-engage. Expect findings and a repair loop — the POC was un-TDD'd.
 7. **Commit and PR.** Only on a clean verdict, run `/commit`, then open a draft PR per the `git-workflow` rule.
 8. **State the honest limitations** from `reference/honest-limitations.md` in the PR body or to the user.
 9. **Converge** by handing the PR to `autoconverge` by default; use `pr-converge` for paced ticks or `bugteam` for an open-loop audit.

package/skills/release-notes-html/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: release-notes-html
+description: Build a polished self-contained HTML product launch and release-notes page from work completed in the current session, using available repository state, source-of-truth files, tests, approvals, artifacts, commits, pull requests, previews, and release evidence. Use when the user asks to build release notes, create a launch page, document completed work, produce feature-release HTML, or turn the session into product-facing release notes.
+when_to_use: Invoke for requests such as "build release notes for the work you've done," "create release notes HTML," "make a product launch page," "document this completed feature," or "turn our work into a polished release page."
+disable-model-invocation: false
+user-invocable: true
+---
+
+Build a polished, self-contained HTML product launch and release-notes page for the work completed in this session.
+
+Use the current conversation, task history, repository state, completed changes, test results, approvals, generated artifacts, plans, handoffs, file paths, commits, pull requests, and other evidence already available in the session as the source of truth.
+
+Recover the feature name, purpose, capabilities, specifications, usage instructions, validation results, release status, and first production use directly from the available context. Inspect relevant files and repository artifacts when access is available.
+
+Ask one concise clarification question only when the session does not contain enough information to identify the completed feature or its supporting evidence.
+
+## Execution
+
+Act as the orchestrator.
+
+Create a task ledger covering:
+
+- Evidence collection
+- Feature and release-state synthesis
+- Page structure
+- HTML creation
+- Evidence audit
+- Visual and browser review
+- Final delivery
+
+Assign file inspection and HTML creation to executor workers when worker tools are available. The orchestrator owns the structure, factual acceptance, and final audit.
+
+## Evidence rules
+
+Use only facts supported by:
+
+- The current conversation
+- Current session tasks and results
+- Repository files and git state
+- Named source-of-truth files
+- Generated reports, ledgers, plans, and acceptance packets
+- Explicit user approvals
+- Test and CI output already available
+- Pull request and commit data available to the session
+
+Locate the strongest source for each claim.
+
+Preserve exact:
+
+- Feature and package names
+- File paths
+- Commands
+- Dimensions
+- Flags
+- Identifiers
+- JSON keys
+- Test totals
+- Pull request numbers
+- Branch and release status
+
+Place exact technical values inside `<code>` elements.
+
+Include previews, approval claims, test counts, merged status, and production-use claims when the available evidence supports them.
+
+## Page content
+
+Produce one cohesive launch page with a clear hierarchy that a non-engineer can skim.
+
+Include the sections that the completed work supports:
+
+1. Hero with the feature name and primary benefit
+2. A brief explanation of what the feature enables
+3. Major capability highlights
+4. How to run or use it
+5. Exact specifications
+6. Quality, validation, and safety coverage
+7. First production use, debut project, or approved example
+8. Current availability or completion status
+
+Adapt the section names and structure to the actual project. Give every heading a useful takeaway.
+
+## Tone
+
+Write the page as the launch of a completed new capability.
+
+Use present-state product copy focused on:
+
+- What it is
+- What the user can accomplish
+- How it works
+- How to use it
+- What guarantees or validations it provides
+- Where it has already been applied
+
+Keep implementation history, discarded approaches, debugging chronology, and internal justification outside the page unless they are essential to using the feature.
+
+## Voice rules
+
+The reader primarily absorbs headings, bolded leads, and the first sentence of each block.
+
+1. Every title states a plain-language claim.
+2. Each sentence carries one idea.
+3. Lead with reader meaning, then explain the mechanism.
+4. Explain specialized terms at first use.
+5. Keep exact technical values verbatim inside `<code>` elements.
+6. Limit cards to two sentences.
+7. Limit list items to three sentences.
+8. Give each section a one-sentence subtitle that adds information.
+9. Make the complete story understandable from headings and bolded leads alone.
+10. Use concise, active sentences.
+11. Use present-state language throughout.
+12. Give every important fact one clear location.
+
+## Design
+
+Create one valid HTML file with self-contained CSS. CDN-hosted fonts are acceptable.
+
+Use:
+
+- Strong visual hierarchy
+- Spacious typography
+- Scannable cards and sections
+- Responsive desktop and narrow-screen layouts
+- Accessible contrast
+- Clear treatment of code, specifications, and commands
+- An inviting product-launch presentation rather than dense documentation
+
+Use an approved preview or product image when one is already available and supported by the session.
+
+## Output location
+
+Choose the output location from an explicit path already stated in the session.
+
+When no output path has been established, write the file beside the project’s existing results, release, report, or acceptance artifacts using a clear name such as:
+
+`RELEASE_NOTES.html`
+
+Use the operating-system temporary directory only when no project location can be determined safely.
+
+Write the file atomically and create its parent directory when required.
+
+## Acceptance audit
+
+Before delivery:
+
+- Verify every factual claim against the available evidence.
+- Review every heading for a clear takeaway.
+- Review every sentence for one idea.
+- Confirm specialized terms receive plain explanations.
+- Confirm exact technical values remain verbatim.
+- Confirm headings and bolded leads communicate the whole story.
+- Confirm the page is readable at desktop and narrow browser widths.
+- Confirm the output is one complete, valid HTML file.
+- Open the completed page in Chrome or the available default browser when the environment supports it.
+- Correct every issue found during the audit.
+
+## Delivery
+
+Reply with:
+
+1. The full absolute path to the HTML file.
+2. One sentence describing what the release-notes page covers.
+
+Stop after delivering the completed page.

package/skills/session-log/SKILL.md

@@ -25,7 +25,7 @@ Sessions come in many shapes — convergence loops, feature builds, research div
 - **The `Artifact` tool wraps the file in a document skeleton at publish time.** It adds `<!doctype html>…<head>…</head><body>` around whatever the file holds — write page content only (a `<title>`, a `<style>` block, and the body markup). Do not include `<!DOCTYPE>`, `<html>`, `<head>`, or `<body>` tags in the file itself.
 - **The `Artifact` tool redeploys to the same URL only within the current run.** Editing the session's HTML file in a later step of this same skill run and calling `Artifact` again does not mint a new URL — it updates the same published page in place. A fresh session has no memory of an artifact's URL from an earlier run, so republishing a session report written in a prior session always mints a new URL (there is no other way to target the old one without the user supplying it).
 - **Vault paths sit outside `.claude/`.** Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside the project tree. Session reports use HTML regardless of vault location — the Artifact tool needs a written file to publish.
-- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html, but the rule at `~/.claude/rules/no-historical-clutter.md` applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
+- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html, but the rule at `~/.claude/rules/doc-prose-cuts.md` applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
 - **`write_existing_file_blocker` rejects Write on existing paths.** Use Write only when creating a fresh session report; use Edit for the vault-context append in step 3.
 - **Obsidian frontmatter index is HTML-blind.** Obsidian's native YAML-frontmatter parser reads only `.md` files. HTML files do not appear in Obsidian's frontmatter index. Search by content still works; search by `type: session-report` does not.
 

package/skills/task-build/CLAUDE.md

@@ -1,28 +1,29 @@
 # task-build
 
-Gathers every open task in the current session and registers each one on the task list with `TaskCreate`.
+Gathers every open task in the current session and registers each one with the best available task or plan tool.
 
 **Trigger:** `/task-build`, "build my task list", "capture these tasks", "add open tasks to the task list", "track these".
 
 ## Purpose
 
-Collects outstanding work from the conversation, `$ARGUMENTS`, and any plan documents or `TodoWrite` items raised this session, then creates one task per open item — skipping anything already tracked or already complete.
+Collects outstanding work from the conversation, `$ARGUMENTS`, and any plan documents or task items raised this session, then registers one item per open task — skipping anything already tracked or already complete.
 
 ## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | The complete skill — four steps (read current list, find open tasks, create one task per item, report). No companion files. |
+| `SKILL.md` | Complete task discovery and registration workflow |
+| `reference/tool-routing.md` | Progressive-disclosure routing and fallback rules |
 
 ## How the skill runs
 
-1. Calls `TaskList` to read what is already tracked — prevents duplicates.
+1. Reads the current list or visible plan with the selected host tool — prevents duplicates.
 2. Scans `$ARGUMENTS`, the conversation, and any plan or checklist items for open, actionable work.
-3. Calls `TaskCreate` for each untracked item with a short imperative `subject`, a `description` of what done looks like, and an optional `activeForm` for the spinner.
-4. Reports how many tasks were added and how many were already tracked.
+3. Prefers `update_plan`; otherwise uses `TaskList`/`TaskCreate`, then `TodoWrite` as the fallback. See `reference/tool-routing.md` for field mapping.
+4. Reports the selected tool, how many tasks were added, and how many were already tracked.
 
 ## Conventions
 
 - This skill only records tasks — it does not start, assign, or complete them.
-- Use `TaskUpdate` to set status or owner after the list is built.
+- Use the matching host operation to set status after the list is built.
 - `disable-model-invocation: true` is not set; the skill uses model judgment to classify open vs. complete items.

package/skills/task-build/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: task-build
-description: "Gather every open task in the current session and register each one on the task list with TaskCreate. Use at the start of work, after a planning discussion, or whenever the user lists several things to do. Triggers: '/task-build', 'build my task list', 'capture these tasks', 'add open tasks to the task list', 'track these'."
+description: "Gather open session tasks and register them with the best available task or plan tool. Triggers: '/task-build', 'build my task list', 'capture these tasks', 'add open tasks to the task list', 'track these', task list, update plan."
 argument-hint: "[optional: a list of tasks to capture, or omit to scan the session]"
 ---
 
 # Task Build
 
-Collect every open task and put it on the session task list. Each open task becomes one `TaskCreate` entry, so all the work is tracked and visible.
+Collect every open task and put it on the session task list or plan using the best available host tool. Read [tool-routing.md](reference/tool-routing.md) only when choosing or adapting the host-tool path.
 
 ## Instructions
 
-1. **Read the current list first.** Call `TaskList` to see what is already tracked. This keeps you from adding the same task twice.
+1. **Read the current list first.** Use the read operation paired with the selected host tool when one exists. If `update_plan` is the selected tool, inspect the current visible plan when available because `update_plan` replaces the full plan.
 
 2. **Find every open task.** Gather all outstanding work from these sources:
    - `$ARGUMENTS`, when the user passed a list.
@@ -19,13 +19,21 @@ Collect every open task and put it on the session task list. Each open task beco
 
    An open task is any concrete, actionable item that is not finished. Skip anything already complete and anything already on the list.
 
-3. **Create one task per item.** For each open task that is not already tracked, call `TaskCreate` with:
-   - `subject` — a short imperative title (e.g. "Fix login redirect").
-   - `description` — what the task involves and how to tell it is done.
-   - `activeForm` — the present-continuous form for the spinner (e.g. "Fixing login redirect"), when it adds clarity.
+3. **Register one item per task.** Prefer `update_plan` when it is available. Otherwise use the first supported task-list method described in [tool-routing.md](reference/tool-routing.md), preserving the complete existing list when the selected tool replaces it.
 
 4. **Report the result.** State how many tasks you added and how many were already tracked, then list the new subjects.
 
 ## Scope
 
-This skill only records tasks. It does not start, assign, or complete them. Use `TaskUpdate` to set an owner or change status once the list is built.
+This skill only records tasks. It does not start, assign, or complete them. Report the selected tool, how many items were added, and how many were already tracked. Use the matching host operation to change status later.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Task discovery and registration hub |
+| `reference/tool-routing.md` | On-demand host-tool selection and field mapping |
+
+## Folder map
+
+- `reference/` — host-tool routing details loaded only when needed

package/skills/task-build/reference/tool-routing.md

@@ -0,0 +1,19 @@
+# Task Tool Routing
+
+Use the first available path in this order:
+
+1. **`update_plan`** — preferred when exposed. Call it once with the complete plan. Map each task to `{step, status}`. Use `pending`, `in_progress`, or `completed`.
+2. **`TaskList` + `TaskCreate`** — use the existing task-list workflow when `update_plan` is unavailable. Create one task per new item with `subject`, `description`, and optional `activeForm`.
+3. **`TodoWrite`** — use when neither `update_plan` nor `TaskCreate` is exposed. Preserve the host's required schema and register the complete current task set.
+
+Do not invent a tool name. Tool availability means the callable tool is exposed in the current session, not merely mentioned in documentation or in another host's skill.
+
+## Status and replacement rules
+
+- When a tool replaces the complete list, include existing unfinished items in the replacement payload.
+- When a tool supports incremental creation, skip duplicates and completed items.
+- If no task or plan tool is exposed, report that fact and keep the work unregistered; do not use a markdown checklist as a substitute.
+
+## Reporting
+
+State the selected tool, the number of new items, the number already tracked, and the new task subjects. If the fallback path was used, name the unavailable preferred tools briefly.