From 89887d06998a953b0606e37c52855e3948e07b06 Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Tue, 3 Nov 2026 05:12:48 +0000 Subject: [PATCH 1/3] Resolve issue #12692 Lane-Activity: work-resolve-issue/resolve-issue --- ...ssue-issue-12692-41580969309-1-0acdfa65.md | 12 +++++++++ ...ssue-issue-12692-41580969309-1-0ad9cc1f.md | 11 ++++++++ ...ssue-issue-12692-41580969309-1-962cd0b0.md | 10 +++++++ .../skills/audit-dead-code/SKILL.md | 26 ++++++++++++------- .../audit-dead-code/context/adjudication.md | 19 ++++++++------ .../skills/batch-simplify/SKILL.md | 10 +++---- .../skills/tidy/lanes/self-update.md | 4 +-- .../skills/tidy/reference/exclusions.md | 4 +-- plugins/planning/skills/design/SKILL.md | 13 +++++----- .../skills/draft-goal-condition/SKILL.md | 26 ++++++++++--------- plugins/planning/skills/interview/SKILL.md | 8 +++--- plugins/planning/skills/plan/SKILL.md | 12 ++++----- plugins/planning/skills/prd/SKILL.md | 2 +- .../repo-fleet-hygiene/skills/audit/SKILL.md | 25 +++++++++++------- 14 files changed, 113 insertions(+), 69 deletions(-) create mode 100644 .changes/code-tidying/work-resolve-issue-issue-12692-41580969309-1-0acdfa65.md create mode 100644 .changes/planning/work-resolve-issue-issue-12692-41580969309-1-0ad9cc1f.md create mode 100644 .changes/repo-fleet-hygiene/work-resolve-issue-issue-12692-41580969309-1-962cd0b0.md diff --git a/.changes/code-tidying/work-resolve-issue-issue-12692-41580969309-1-0acdfa65.md b/.changes/code-tidying/work-resolve-issue-issue-12692-41580969309-1-0acdfa65.md new file mode 100644 index 00000000000..58cbe10daa4 --- /dev/null +++ b/.changes/code-tidying/work-resolve-issue-issue-12692-41580969309-1-0acdfa65.md @@ -0,0 +1,12 @@ +--- +bump: patch +--- + +### Changed + +- `/code-tidying:audit-dead-code`, `/code-tidying:batch-simplify` and the `/code-tidying:tidy` + self-update lane and exclusions reference no longer restate upstream behavior (LSP reference + counting, detector exit codes, gopls and staticcheck suppression, knip and vulture config + details, how injected commands run, git's `--since` parsing, frontmatter loading, hook + locations, `userConfig` types). Each keeps its own rule and links the upstream section with an + as-of date and a recheck trigger. The self-update lane drops its note on how consumers update. diff --git a/.changes/planning/work-resolve-issue-issue-12692-41580969309-1-0ad9cc1f.md b/.changes/planning/work-resolve-issue-issue-12692-41580969309-1-0ad9cc1f.md new file mode 100644 index 00000000000..1ec156c6d97 --- /dev/null +++ b/.changes/planning/work-resolve-issue-issue-12692-41580969309-1-0ad9cc1f.md @@ -0,0 +1,11 @@ +--- +bump: patch +--- + +### Changed + +- `/planning:design`, `/planning:plan`, `/planning:prd`, `/planning:interview` and + `/planning:draft-goal-condition` no longer restate upstream behavior (how injected commands run, + Mermaid's C4 support, plan mode, the `/plan` command, the `Plan` subagent, the `/goal` + evaluator, limit and permissions). Each keeps its own rule and links the upstream section with + an as-of date and a recheck trigger. diff --git a/.changes/repo-fleet-hygiene/work-resolve-issue-issue-12692-41580969309-1-962cd0b0.md b/.changes/repo-fleet-hygiene/work-resolve-issue-issue-12692-41580969309-1-962cd0b0.md new file mode 100644 index 00000000000..8fa179e0eb6 --- /dev/null +++ b/.changes/repo-fleet-hygiene/work-resolve-issue-issue-12692-41580969309-1-962cd0b0.md @@ -0,0 +1,10 @@ +--- +bump: patch +--- + +### Changed + +- `/repo-fleet-hygiene:audit` no longer restates git worktree list ordering, GitHub's GraphQL + limits, Git Bash's handling of Windows junctions, or what `core.bare` does and its remedy + command (`bare-repo-with-working-tree` stays manual review). It keeps its own + rules and links the upstream sections with an as-of date and a recheck trigger. diff --git a/plugins/code-tidying/skills/audit-dead-code/SKILL.md b/plugins/code-tidying/skills/audit-dead-code/SKILL.md index 658aa611819..a8d97785178 100644 --- a/plugins/code-tidying/skills/audit-dead-code/SKILL.md +++ b/plugins/code-tidying/skills/audit-dead-code/SKILL.md @@ -120,10 +120,11 @@ Bounded by design. Evidence catalogue: [context/adjudication.md](context/adjudic [context/adjudication.md, Bounding the pass](context/adjudication.md#bounding-the-pass); relay as of 2026-10-11, recheck when that record's pointer moves out of that section). 6. **Optional LSP assist**, never required and never a lane: when Claude Code's `LSP` tool is - available, `findReferences` on one candidate is one more evidence source. `includeDeclaration` - is hard-coded true, so the dead threshold is `resultCount == 1`; imports count as references, - so a re-export still reads alive. Done when every emitted candidate has a `dead`, `uncertain` - or `alive` verdict with evidence, or the cap stopped the batch and the report says so. + available, `findReferences` on one candidate is one more evidence source. Read what it returns + in [LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior) + before reading a count as dead (as of 2026-11-03; recheck when that section changes what + `findReferences` returns). Done when every emitted candidate has a `dead`, `uncertain` or + `alive` verdict with evidence, or the cap stopped the batch and the report says so. ## Hard rules @@ -138,8 +139,10 @@ Bounded by design. Evidence catalogue: [context/adjudication.md](context/adjudic `Summary total:` mean two things. - **T3 is the drift bucket.** An unrecognized detector line is recorded, never dropped and never counted as a finding. A fourth verdict landing there is the alarm, not the answer. -- **Exit codes are never run health.** knip exits 1 for findings and for hard errors; vulture - exits 3 for findings and 1 for a lone unparsable input; gopls always exits 0. +- **Exit codes are never run health.** Run health comes from the detector's output, never its + exit code. Each detector's codes: [vulture](https://github.com/jendrikseipp/vulture#exit-codes), + [knip](https://knip.dev/reference/cli#--no-exit-code), [gopls](https://go.dev/gopls/command-line). + As of 2026-11-03; recheck when one of those sections changes its exit codes. - **Presence is proven by invocation**, never by a locator hit (measured: `command -v rust-analyzer` succeeds while invocation fails). - **knip evaluates repo-controlled config through jiti.** Disclose it on every run that loads one. @@ -205,10 +208,13 @@ formats"), and the next run reaches new code. Each step is done when the operato verdicts and suppression text, has declined them, or the batch is explicitly deferred; the loop ends when a follow-up scan is scheduled or the operator stops after one batch. -Only knip and vulture converge. **Go and the grep lane have no native suppression** (measured: -`gopls check -severity=hint` reports through every candidate directive; `//lint:ignore` is -staticcheck's), so those verdicts live in the report and in a comment at the declaration, and the -same candidates return. Say so rather than emitting a directive that does nothing. +Only knip and vulture converge. **Go and the grep lane get no suppression directive**: those +verdicts live in the report and in a comment at the declaration, and the same candidates return. +Say so rather than emitting a directive. The probe behind the Go half is in +[context/adjudication.md](context/adjudication.md#suppression-formats) "Suppression formats"; `//lint:ignore` belongs +to staticcheck, per +[Ignoring problems with linter directives](https://staticcheck.dev/docs/configuration/#ignoring-problems-with-linter-directives) +(as of 2026-11-03; recheck when that section names gopls among the tools that read it). `dead` and `uncertain` verdicts are session-scoped: an un-suppressed `uncertain` returns next run. A committed vulture whitelist raises `F821` under a consumer's ruff config; say so when you emit diff --git a/plugins/code-tidying/skills/audit-dead-code/context/adjudication.md b/plugins/code-tidying/skills/audit-dead-code/context/adjudication.md index 4668b1b41bf..057701ab13d 100644 --- a/plugins/code-tidying/skills/audit-dead-code/context/adjudication.md +++ b/plugins/code-tidying/skills/audit-dead-code/context/adjudication.md @@ -28,9 +28,9 @@ Cheap checks first, in this order: a repo-wide literal search for the bare name strings), then the config surfaces, then the framework-registration patterns for the candidate's language. Stop at the first piece of real evidence. -The optional `LSP` assist is one more source, never a substitute: `findReferences` with -`includeDeclaration` hard-coded true means the dead threshold is `resultCount == 1`, and an import -counts as a reference, so a re-export still reads alive. +The optional `LSP` assist is one more source, never a substitute. What `findReferences` returns: +[LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior), as of +2026-11-03; recheck when that section changes what `findReferences` returns. ## Verdict rules @@ -66,7 +66,7 @@ parser recognized, and it is a bug report about the detector, not a finding abou The skill writes nothing. It emits ready-to-paste text and the human decides. -**knip**, in `knip.json` (or the `knip` key in `package.json`): +**knip**, an `ignore` entry for the project's knip config, emitted as JSON: ```json { @@ -75,16 +75,19 @@ The skill writes nothing. It emits ready-to-paste text and the human decides. } ``` -Note that a `knip.config.ts` is a **code module** knip evaluates through jiti; the JSON form does -not cross that boundary and is the safer paste when either will do. +Where knip reads its config and what `ignore` takes: +[ignore](https://knip.dev/reference/configuration#ignore), as of 2026-11-03; recheck when that +section changes what an `ignore` entry takes. -**vulture**, a whitelist file passed alongside the sources: +**vulture**, a whitelist entry carrying the adjudication as its comment: ```python -# whitelist.py: names vulture must treat as used. format_legacy_row # adjudicated alive: dispatched by name from handlers.py ``` +How vulture reads a whitelist: [Whitelists](https://github.com/jendrikseipp/vulture#whitelists), +as of 2026-11-03; recheck when that section changes how a whitelist is passed. + **A committed vulture whitelist raises `F821` (undefined name) under a consumer's ruff config.** Say so whenever you emit one; the consumer either excludes the file in `ruff.toml` or keeps the whitelist out of the linted tree. diff --git a/plugins/code-tidying/skills/batch-simplify/SKILL.md b/plugins/code-tidying/skills/batch-simplify/SKILL.md index 5f90ef40eb2..1dedee7c95c 100644 --- a/plugins/code-tidying/skills/batch-simplify/SKILL.md +++ b/plugins/code-tidying/skills/batch-simplify/SKILL.md @@ -60,11 +60,9 @@ invocation: - Current branch, `git branch --show-current` Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as -separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute -block as one shell invocation, and a worktree-isolated session refuses a compound command that -contains git. The dated record for that composition claim is the -[gather-block convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/gather-block/README.md#the-pre-compute-block-runs-as-one-shell-invocation), -"The pre-compute block runs as one shell invocation". +separate body Bash calls rather than pre-compute lines. How the harness runs a skill's injected +commands: [How injected commands run](https://code.claude.com/docs/en/skills#how-injected-commands-run), +as of 2026-11-03; recheck when that section changes how injected commands run. ## Variables @@ -87,7 +85,7 @@ For any batch run (Phases 1-8), copy `templates/checklist.md` into your project' Supported formats: `24h`, `48h`, `72h`, `7d`, `2d`, `1w`. Default: `48h`. -**Normalize before use:** git's `--since` approxidate parser requires `24 hours`, not `24h`. Convert before passing to `git log`: +**Normalize before use:** convert to long units before passing the window to `git log --since` (the option's entry is under [Commit Limiting](https://git-scm.com/docs/git-log#_commit_limiting), as of 2026-11-03; recheck when that entry documents the short `h`, `d` and `w` forms): - `h` → ` hours` (e.g., `48h` → `48 hours`) - `d` → ` days` (e.g., `7d` → `7 days`) diff --git a/plugins/code-tidying/skills/tidy/lanes/self-update.md b/plugins/code-tidying/skills/tidy/lanes/self-update.md index 9ad6bb64d04..dc8e49365cb 100644 --- a/plugins/code-tidying/skills/tidy/lanes/self-update.md +++ b/plugins/code-tidying/skills/tidy/lanes/self-update.md @@ -1,6 +1,6 @@ # Lane: self-update -The recursive lane: tidy operating on its own plugin files. **Maintainer-facing:** valid ONLY in a working-tree checkout of this plugin (the marketplace clone, or a directory loaded via `--plugin-dir`), never against an installed marketplace copy. Consumers receive updates through `/plugin marketplace update`. **This lane is permanently manual-merge.** The risk profile is unique: a bad change here can disable the safety mechanisms that protect every other lane. +The recursive lane: tidy operating on its own plugin files. **Maintainer-facing:** valid ONLY in a working-tree checkout of this plugin (the marketplace clone, or a directory loaded via `--plugin-dir`), never against an installed marketplace copy. **This lane is permanently manual-merge.** The risk profile is unique: a bad change here can disable the safety mechanisms that protect every other lane. ## Scope @@ -48,7 +48,7 @@ npx markdownlint-cli2 bash skills/tidy/scripts/open-pr-count.test.sh # if the script changed (it shouldn't in this lane) ``` -Markdown lint does not cover the frontmatter parse contract. A broken `---` fence in a SKILL.md would block the next session's skill discovery. Run from the plugin root: +Markdown lint does not cover the frontmatter parse contract, so run this fence check from the plugin root. How Claude Code reads a SKILL.md's frontmatter block: [Frontmatter reference](https://code.claude.com/docs/en/skills#frontmatter-reference), as of 2026-11-03; recheck when that section changes how a malformed frontmatter block loads. ```bash # Stdlib-only (no PyYAML): confirms each SKILL.md's `---` fences are present and the frontmatter between them is non-empty. diff --git a/plugins/code-tidying/skills/tidy/reference/exclusions.md b/plugins/code-tidying/skills/tidy/reference/exclusions.md index 7bd63506f35..4bb64d5dd05 100644 --- a/plugins/code-tidying/skills/tidy/reference/exclusions.md +++ b/plugins/code-tidying/skills/tidy/reference/exclusions.md @@ -18,7 +18,7 @@ The GLOBAL HARD list gates every lane. A tidying that would touch any entry is a ### Agent & enforcement configuration (universal) -Claude Code surface: `.claude/**` in full. The whole directory is agent surface: settings, agents, hooks, rules, routines, tidy-lanes (the consumer's own lane definitions, since the lane contract cannot tidy itself), and any settings-wired hook or bootstrap script that lives there. Any script wired as a hook command **anywhere** is excluded wherever it lives, because a hook command may point outside `.claude/`. Hook wiring is not only the project settings scope (`.claude/settings.json`, `.claude/settings.local.json`): a plugin's `hooks/hooks.json` and a skill's or agent's frontmatter `hooks` block wire hook commands too, and a script reached through either is excluded on the same footing. `.mcp.json`. Other agents' config bundles (e.g. `.codex/**`, `.cursor/**`), since a tidy must not mutate another agent's behavior. GitHub surface: `.github/workflows/**`, `.github/actions/**`, `.github/CODEOWNERS`, `.github/dependabot.yml`. Local git-hook chain: the hook manager's config and script directories (e.g. `lefthook.yml`, `.lefthook/**`, `.husky/**`, `.pre-commit-config.yaml`). Cross-ecosystem lint / style config: `.editorconfig`, `.shellcheckrc`, and their per-tool equivalents. +Claude Code surface: `.claude/**` in full. The whole directory is agent surface: settings, agents, hooks, rules, routines, tidy-lanes (the consumer's own lane definitions, since the lane contract cannot tidy itself), and any settings-wired hook or bootstrap script that lives there. Any script wired as a hook command **anywhere** is excluded wherever it lives, because a hook command may point outside `.claude/`. Every place a hook can be wired counts, not only the project settings files: see [Hook locations](https://code.claude.com/docs/en/hooks#hook-locations), as of 2026-11-03; recheck when that section adds or removes a location. `.mcp.json`. Other agents' config bundles (e.g. `.codex/**`, `.cursor/**`), since a tidy must not mutate another agent's behavior. GitHub surface: `.github/workflows/**`, `.github/actions/**`, `.github/CODEOWNERS`, `.github/dependabot.yml`. Local git-hook chain: the hook manager's config and script directories (e.g. `lefthook.yml`, `.lefthook/**`, `.husky/**`, `.pre-commit-config.yaml`). Cross-ecosystem lint / style config: `.editorconfig`, `.shellcheckrc`, and their per-tool equivalents. ### Consumer-declared protections @@ -122,7 +122,7 @@ To operate on a directory genuinely named `override`, spell it `./override`. ### The `hard_exclusions` userConfig option -`enforce` (default) keeps the section 1 path list blocking. `advisory` reports each HARD path match and never blocks, so the operator's standing posture is "tell me, then proceed". It is a scalar, not a list: `userConfig` types are `string`, `number`, `boolean`, `directory`, and `file`, so a per-path list cannot live there and belongs in the repository file below. Any value outside the two is read as `enforce`. +`enforce` (default) keeps the section 1 path list blocking. `advisory` reports each HARD path match and never blocks, so the operator's standing posture is "tell me, then proceed". It is a scalar, not a list: a per-path list belongs in the repository file below. Option types: [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration), as of 2026-11-03; recheck when that section changes the option types. Any value outside the two is read as `enforce`. ### The consumer-declared overrides file diff --git a/plugins/planning/skills/design/SKILL.md b/plugins/planning/skills/design/SKILL.md index 8b986325e83..f8e95ea9779 100644 --- a/plugins/planning/skills/design/SKILL.md +++ b/plugins/planning/skills/design/SKILL.md @@ -19,10 +19,9 @@ Collect these with **individual** Bash calls, one command per call, never combin - Current branch, `git branch --show-current` Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as -body Bash calls, not pre-compute lines: a worktree-isolated session refuses a compound command that -contains git, and the pre-compute block runs as one. Record: the -[gather-block convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/gather-block/README.md#the-pre-compute-block-runs-as-one-shell-invocation), -"The pre-compute block runs as one shell invocation". +body Bash calls, not pre-compute lines. How the harness runs a skill's injected commands: +[How injected commands run](https://code.claude.com/docs/en/skills#how-injected-commands-run), as +of 2026-11-03; recheck when that section changes how injected commands run. ## Variables @@ -338,7 +337,7 @@ file. After the gate passes, the handoff output names those files and signatures | `module` | domain-model.md, module-boundary.md, contracts.md, design-threads.md | none | none (no typed artifact, so no scope label) | | `data` | entity-relationships.md, schema-decisions.md, design-threads.md | `entity-relationships.md` | mermaid `erDiagram` by default; DBML when `diagram_dialect.data` resolves to `dbml` | | `integration` | contract-spec.md, sequence-flows.md, design-threads.md | `sequence-flows.md`, `contract-spec.md` | mermaid `sequenceDiagram` for the flows; an OpenAPI 3.1 sketch for the contract spec | -| `system` | component-map.md, communication-patterns.md, design-threads.md | `component-map.md`, and only when `diagram_dialect.system` names a dialect | a C4 container view in LikeC4 or C4-PlantUML. Never Mermaid's experimental C4 support | +| `system` | component-map.md, communication-patterns.md, design-threads.md | `component-map.md`, and only when `diagram_dialect.system` names a dialect | a C4 container view in LikeC4 or C4-PlantUML, never Mermaid's [C4 diagrams](https://mermaid.js.org/syntax/c4.html#c4-diagrams) (as of 2026-11-03; recheck when that page changes which C4 features it supports) | `design-threads.md` is common across all scopes. @@ -390,8 +389,8 @@ it, emit the plainest correct form of the dialect. The typed artifact is produce for the round after it resolves. Render a round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`; unexpanded or empty means off) is on and the round is independent questions that fit one `AskUserQuestion` call (the per-call question limit: - , as of 2026-10-11; recheck - when that section changes the per-call question limit). Inline prose otherwise + , as of 2026-10-11; + recheck when that section changes the per-call question limit). Inline prose otherwise - **Grounding steps.** Ground a consequential recommendation in the affected code plus its consumers and in external research that reads official docs first, routed to `/discovery:explore` and `/discovery:research` if enabled. A recommendation that changes is diff --git a/plugins/planning/skills/draft-goal-condition/SKILL.md b/plugins/planning/skills/draft-goal-condition/SKILL.md index b9ac8aa1545..4b48e8631b3 100644 --- a/plugins/planning/skills/draft-goal-condition/SKILL.md +++ b/plugins/planning/skills/draft-goal-condition/SKILL.md @@ -124,10 +124,11 @@ defers until the docs are reachable. Never finalize a draft on a shape or limit ## Step 2. Draft the condition -The evaluator judges the condition against **what Claude has already surfaced in the transcript**; -it does not run commands or read files. Every claim in the condition must be something Claude's own -output can demonstrate. Avoid conditions the transcript cannot show (subjective quality, external -state Claude never surfaces). +Every claim in the condition must be something Claude's own output in the transcript can +demonstrate. Avoid conditions the transcript cannot show (subjective quality, external state Claude +never surfaces). What the evaluator reads: +[How evaluation works](https://code.claude.com/docs/en/goal#how-evaluation-works), as of +2026-11-03; recheck when that section changes what the evaluator receives or can call. Structure the draft to the shape Step 1 read off the live page; this file does not restate its elements. Keep each prescribed element separately identifiable, so Step 3's tightening pass can @@ -181,9 +182,8 @@ on the wrong evidence. Build the Step 1 shape from these three moves; they feed verdict. "…a report where you have verified every citation by fetching it and confirming the page supports the claim" is checkable; "…a report whose citations are correct" is not. -The judgment is not self-review: it is delegated to a fresh-context evaluator model that receives -only the condition and the conversation and calls nothing, so move 3 is credited only by verification Claude **performed in the transcript**; a -claim that checking happened reads the same as the checking. Word it so the doing leaves visible +Move 3 is credited only by verification Claude **performed in the transcript** (the evaluator +pointer is in Step 2); a claim that checking happened reads the same as the checking. Word it so the doing leaves visible output (the fetches, the diffs, the command runs). Subjective quality stays out of the condition except as whatever moves 1–3 made observable. @@ -287,13 +287,15 @@ in [reference/native-goal.md](reference/native-goal.md). substitute a token estimate. - **Never hardcode the limit or the shape** into a draft, this file, or the script. They are read live each run. -- **Over-limit submission behavior is undocumented**. There is no stated truncation or rejection - semantics, so the pre-submission counter is the only guard. Do not assume the app will trim. +- **The pre-submission counter is the only length guard.** Do not assume the app trims an + over-limit condition. The limit is in + [Write an effective condition](https://code.claude.com/docs/en/goal#write-an-effective-condition), + as of 2026-11-03; recheck when that section says what happens to an over-limit condition. - **A long goal run draws usage on every turn.** We treat a goal left waiting on background work as still spending usage, so flag it when drafting a goal that waits on background work. Pointer: for why usage climbs in a long session and the setting that turns goal check-ins off, see . As of: 2026-10-01. Recheck trigger: that section moves or stops naming goal check-ins. -- **A goal does not change permissions.** If the stated check runs a command, the user still gets - asked unless auto mode or their settings already allow it. Flag it when the check is a shell - command. +- **Flag a goal whose check is a shell command**, and point the user at + [Set a goal](https://code.claude.com/docs/en/goal#set-a-goal) for how goal turns get permission, + as of 2026-11-03; recheck when that section changes how a goal interacts with permission modes. diff --git a/plugins/planning/skills/interview/SKILL.md b/plugins/planning/skills/interview/SKILL.md index 3483b019d8c..65319ef0f3b 100644 --- a/plugins/planning/skills/interview/SKILL.md +++ b/plugins/planning/skills/interview/SKILL.md @@ -24,11 +24,9 @@ bounds nothing: the Bash tool returns the command's complete output into context anything to decide about. Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as -separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute -block as one shell invocation, and a worktree-isolated session refuses a compound command that -contains git. The dated record for that composition claim is the -[gather-block convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/gather-block/README.md#the-pre-compute-block-runs-as-one-shell-invocation), -"The pre-compute block runs as one shell invocation". +separate body Bash calls rather than pre-compute lines. How the harness runs a skill's injected +commands: [How injected commands run](https://code.claude.com/docs/en/skills#how-injected-commands-run), +as of 2026-11-03; recheck when that section changes how injected commands run. ## Variables diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index 63de57ff747..bce6958aefe 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -19,7 +19,7 @@ Collect these with **individual** Bash calls, one command per call, never combin - Recent commits, `git log --oneline -5` - Working tree status (empty = clean), `git status --porcelain | head -10` -Keep the pipe in the command: a read-time cap bounds nothing, since the Bash tool returns the full output first. Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as body Bash calls, not pre-compute lines: the pre-compute block runs as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. Dated record: the [gather-block convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/gather-block/README.md#the-pre-compute-block-runs-as-one-shell-invocation), "The pre-compute block runs as one shell invocation". +Keep the pipe in the command: a read-time cap bounds nothing, since the Bash tool returns the full output first. Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as body Bash calls, not pre-compute lines. How the harness runs a skill's injected commands: [How injected commands run](https://code.claude.com/docs/en/skills#how-injected-commands-run), as of 2026-11-03; recheck when that section changes how injected commands run. ## Variables @@ -27,7 +27,7 @@ Arguments: `$ARGUMENTS` ## Purpose -Every implementation starts with a clear design, evidence, a test strategy, and user sign-off before any code is written. This is **not** Claude Code's built-in plan mode (`shift+tab`), which is a read-only *permission mode*; this skill is the *planning discipline* around it. It consumes exploration, research, and `/planning:design` (types, contracts, module boundaries, package topology) and produces a plan the user approves before execution. A 2-minute plan prevents a 20-minute rework cycle. Match planning depth to blast radius: a one-file fix gets a brief plan; a cross-cutting architecture change gets a full plan with stress-testing and research-iterate loops. +Every implementation starts with a clear design, evidence, a test strategy, and user sign-off before any code is written. This is **not** Claude Code's built-in plan mode (what that mode does: [Analyze before you edit with plan mode](https://code.claude.com/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode), as of 2026-11-03; recheck when that section changes what plan mode lets Claude do); this skill is a separate *planning discipline* that can run inside it. It consumes exploration, research, and `/planning:design` (types, contracts, module boundaries, package topology) and produces a plan the user approves before execution. A 2-minute plan prevents a 20-minute rework cycle. Match planning depth to blast radius: a one-file fix gets a brief plan; a cross-cutting architecture change gets a full plan with stress-testing and research-iterate loops. **Skip the plan when one sentence covers the change.** First try to write the whole diff as one sentence. The test passes when no design question is open and that sentence describes every edit. How this skill was reached decides what happens next: @@ -314,10 +314,10 @@ Entering plan mode licenses a **scoping confirm**: a short round of questions th The command and this skill share a name, so "plan this" can mean either. -- **`/plan` (built-in command)**: `/plan [description]` enters plan mode, optionally starting on the description; `/plan open` views the session plan. It is reserved for the person to run; the model does not invoke it. +- **`/plan` (built-in command)**: enters plan mode. Its forms are in the `/plan` row of [All commands](https://code.claude.com/docs/en/commands#all-commands), as of 2026-11-03; recheck when that row changes. This skill offers it to the person and never runs it. - **This skill (marketplace plugin).** The planning discipline: stress-test, blast radius, an approval gate, and a persisted PLAN.md a cleared session can execute. -**Routing.** Where Plan Mode Integration says to suggest plan mode, offer it to the person: If /plan is available in your session (gate basis: not gated behind a setting, though a host may lack it; records in [reference/native-plan.md](reference/native-plan.md)), you can run it (or press `shift+tab`) alongside this skill. Prefer this skill for the plan itself. When the caller passes `--unattended`, the run records the offer in its output instead of asking; without that flag it asks. +**Routing.** Where Plan Mode Integration says to suggest plan mode, offer it to the person: If /plan is available in your session (records in [reference/native-plan.md](reference/native-plan.md)), you can run it (or press `shift+tab`) alongside this skill. Prefer this skill for the plan itself. When the caller passes `--unattended`, the run records the offer in its output instead of asking; without that flag it asks. **Mutation gate.** This skill writes PLAN.md and its checklist; `/plan` changes the permission mode. This skill never toggles the mode on the person's behalf. @@ -327,12 +327,12 @@ The command and this skill share a name, so "plan this" can mean either. Both produce an implementation plan, so "plan this" can also route to the subagent. -- **`Plan` (built-in subagent)**: a research agent that returns a step-by-step approach to its caller, skips CLAUDE.md, and runs no approval gate. It cannot write files. It is reached through the Agent tool's `subagent_type`. +- **`Plan` (built-in subagent)**: reached through the Agent tool's `subagent_type`; this skill's approval gate does not apply to it. Its purpose, context and tools are in [Built-in subagents](https://code.claude.com/docs/en/sub-agents#built-in-subagents), as of 2026-11-03; recheck when that section changes the Plan subagent's purpose or tools. - **This skill (marketplace plugin)**: the plan the person approves: stress-test, blast radius, decision gates, and a persisted PLAN.md. **Routing.** When the built-in `Plan` agent resolves in this session, dispatch it for a throwaway approach sketch or read-only context-gathering whose result feeds other work; use this skill when the plan needs the person's approval or must outlive the session. This skill may dispatch `Plan` to gather context, but the plan it presents is its own. -**Mutation gate.** `Plan` writes nothing. This skill writes PLAN.md and its checklist. +**Mutation gate.** This skill writes PLAN.md and its checklist; a dispatched `Plan` agent never writes them. The four-part records live in [reference/native-plan-agent.md](reference/native-plan-agent.md). diff --git a/plugins/planning/skills/prd/SKILL.md b/plugins/planning/skills/prd/SKILL.md index 22ba2470dbe..6ef7be71ce0 100644 --- a/plugins/planning/skills/prd/SKILL.md +++ b/plugins/planning/skills/prd/SKILL.md @@ -18,7 +18,7 @@ Collect these with **individual** Bash calls, one command per call, never combin - Recent commits, `git log --oneline -5` - Working tree status (empty = clean), `git status --porcelain | head -10` -Keep the pipe in the command: a read-time cap bounds nothing, since the Bash tool returns the full output first. Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as body Bash calls, not pre-compute lines: the pre-compute block runs as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. Dated record: the [gather-block convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/gather-block/README.md#the-pre-compute-block-runs-as-one-shell-invocation), "The pre-compute block runs as one shell invocation". +Keep the pipe in the command: a read-time cap bounds nothing, since the Bash tool returns the full output first. Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as body Bash calls, not pre-compute lines. How the harness runs a skill's injected commands: [How injected commands run](https://code.claude.com/docs/en/skills#how-injected-commands-run), as of 2026-11-03; recheck when that section changes how injected commands run. ## Variables diff --git a/plugins/repo-fleet-hygiene/skills/audit/SKILL.md b/plugins/repo-fleet-hygiene/skills/audit/SKILL.md index 45e18231036..770bf441b2b 100644 --- a/plugins/repo-fleet-hygiene/skills/audit/SKILL.md +++ b/plugins/repo-fleet-hygiene/skills/audit/SKILL.md @@ -122,11 +122,11 @@ The script validates config with `git config --file`; it never sources or execut The bundled collector is authoritative for classifications. Preserve its evidence in the report: 1. **Canonical checkout:** explicit remote-keyed override → configured remote-keyed override → the - repository's **main worktree**, read as the first record of `git worktree list --porcelain` - (which lists the main worktree first regardless of where it runs). `git rev-parse - --show-toplevel` alone cannot identify a canonical checkout: inside a linked worktree it returns - the linked root, so a sibling worktree reached first by discovery would otherwise become the - path every handoff points at. When a supplied or discovered path resolves to a different main + repository's **main worktree**, read from `git worktree list --porcelain`, never from the + checkout discovery reached first. Which record is the main worktree: git-worktree's + [`list`](https://git-scm.com/docs/git-worktree#Documentation/git-worktree.txt-list) entry and + [List output format](https://git-scm.com/docs/git-worktree#_list_output_format), as of 2026-11-03; recheck when that entry changes the order it lists worktrees + in. When a supplied or discovered path resolves to a different main worktree, the header states the substitution on one `Resolved to main worktree:` line per repository, naming every path that resolved into it. Relay it, because the operator named one path and the report is about another. The report always shows @@ -144,8 +144,11 @@ The bundled collector is authoritative for classifications. Preserve its evidenc (up to `MERGED_PR_GRAPHQL_ALIAS_PAGE` `headRefName` aliases per call, `first:1`, `states:[MERGED]`). GraphQL's `headRefName` argument is an **exact** match, never the search API's prefix-matching `head:` qualifier, so `feature/auth` and `feature/auth-v2` never conflate. - Measured rate cost stays 1 per call (nodeCount equals the alias count); that stays well under - GitHub's documented 500,000-node ceiling and 5,000-point/hour primary limit. There is no merged-PR + Measured rate cost stays 1 per call (nodeCount equals the alias count), well under GitHub's + limits: + [Primary rate limit](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api#primary-rate-limit) + and [Node limit](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api#node-limit), + as of 2026-11-03; recheck when either section changes its limit. There is no merged-PR result window and no per-branch fallback: every non-default local branch the operator asked about is queried by exact name, including heads GitHub auto-deleted and a later fetch pruned. Fail closed when `gh`/GraphQL is unavailable. Emit `github-pr-evidence-unavailable` and never infer unmerged from a missing @@ -335,8 +338,10 @@ Related fleet contracts that remain separate: audit target unless named explicitly via `--repo` / `fleet.repo`. - A symlinked or junctioned intermediate directory under `--root` is not followed, but is disclosed as an `UNKNOWN` `discovery-symlink-skip` finding and counted on the discovery-skips header line. - Like `discovery-skip`, it is disclosure-only and does not make the fleet BLOCKED. Windows - directory junctions test as symlinks under Git Bash, so they take this path. Symlinked + Like `discovery-skip`, it is disclosure-only and does not make the fleet BLOCKED. What a Windows + directory junction is: + [Creating directory junctions](https://gitforwindows.org/symbolic-links.html#creating-directory-junctions), + as of 2026-11-03; recheck when that page moves or covers how Git Bash tests a junction. Symlinked discovery *roots* remain a hard refusal (CLI) or `stale-config-entry` (configured). - `gh` missing/unauthenticated or API/timeout failure: continue Git/worktree checks, report GitHub evidence as `UNKNOWN`, and make no merged/migration claim. Compatible `timeout`/`gtimeout` is @@ -374,7 +379,7 @@ Related fleet contracts that remain separate: | `ls-remote-fleet-unavailable` | Confirm `git ls-remote --heads` works by hand with the operator's usual Git transport, then rerun | | `worktree-root-pluginconfigs-unreadable` | Install `jq`, or set `worktreeroot.path`; do not treat the fleet as unconfigured | | `worktree-placement-unverifiable` | Inspect the canonical checkout; placement was not checked for any of its worktrees, so their placement is unknown rather than confirmed | -| `bare-repo-with-working-tree` | Manual review. `core.bare=true` coincides with working-tree content or registered linked worktrees, so the main worktree is disabled while linked worktrees keep working. Nothing is lost; the documented remedy is `git config --local core.bare false` in the named checkout | +| `bare-repo-with-working-tree` | Manual review: `core.bare=true` coincides with working-tree content or registered linked worktrees. What the setting does: the [`core.bare`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-corebare) entry, as of 2026-11-03; recheck when that entry changes | | `github-remote-moved` | Human-reviewed `git remote set-url`; this plugin never changes remotes | This plugin remains useful if those optional collaborators are absent: the report names the local From 17e75a6abd1ea3f4339bafcadd0dd177ac43b058 Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Tue, 3 Nov 2026 05:28:12 +0000 Subject: [PATCH 2/3] Address review feedback on work-resolve-issue/issue-12692-41580969309-1 Lane-Activity: pr-unblock/address-feedback Lane-Thread: PRRT_kwDOTCGFQM6y_Pzf Lane-Thread: PRRT_kwDOTCGFQM6y_Pzj --- plugins/code-tidying/skills/audit-dead-code/SKILL.md | 6 +++--- plugins/planning/skills/plan/SKILL.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/code-tidying/skills/audit-dead-code/SKILL.md b/plugins/code-tidying/skills/audit-dead-code/SKILL.md index a8d97785178..2df30e8f15f 100644 --- a/plugins/code-tidying/skills/audit-dead-code/SKILL.md +++ b/plugins/code-tidying/skills/audit-dead-code/SKILL.md @@ -140,9 +140,9 @@ Bounded by design. Evidence catalogue: [context/adjudication.md](context/adjudic - **T3 is the drift bucket.** An unrecognized detector line is recorded, never dropped and never counted as a finding. A fourth verdict landing there is the alarm, not the answer. - **Exit codes are never run health.** Run health comes from the detector's output, never its - exit code. Each detector's codes: [vulture](https://github.com/jendrikseipp/vulture#exit-codes), - [knip](https://knip.dev/reference/cli#--no-exit-code), [gopls](https://go.dev/gopls/command-line). - As of 2026-11-03; recheck when one of those sections changes its exit codes. + exit code. The documented codes: [vulture](https://github.com/jendrikseipp/vulture#exit-codes), + [knip](https://knip.dev/reference/cli#--no-exit-code). As of 2026-11-03; recheck when one of + those sections changes its exit codes. - **Presence is proven by invocation**, never by a locator hit (measured: `command -v rust-analyzer` succeeds while invocation fails). - **knip evaluates repo-controlled config through jiti.** Disclose it on every run that loads one. diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index bce6958aefe..c2551788e17 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -317,7 +317,7 @@ The command and this skill share a name, so "plan this" can mean either. - **`/plan` (built-in command)**: enters plan mode. Its forms are in the `/plan` row of [All commands](https://code.claude.com/docs/en/commands#all-commands), as of 2026-11-03; recheck when that row changes. This skill offers it to the person and never runs it. - **This skill (marketplace plugin).** The planning discipline: stress-test, blast radius, an approval gate, and a persisted PLAN.md a cleared session can execute. -**Routing.** Where Plan Mode Integration says to suggest plan mode, offer it to the person: If /plan is available in your session (records in [reference/native-plan.md](reference/native-plan.md)), you can run it (or press `shift+tab`) alongside this skill. Prefer this skill for the plan itself. When the caller passes `--unattended`, the run records the offer in its output instead of asking; without that flag it asks. +**Routing.** Where Plan Mode Integration says to suggest plan mode, offer it to the person: If /plan is available in your session (gate basis: the records in [reference/native-plan.md](reference/native-plan.md)), you can run it (or press `shift+tab`) alongside this skill. Prefer this skill for the plan itself. When the caller passes `--unattended`, the run records the offer in its output instead of asking; without that flag it asks. **Mutation gate.** This skill writes PLAN.md and its checklist; `/plan` changes the permission mode. This skill never toggles the mode on the person's behalf. From dd3a3f7a9c09f659748871ed0de876bc48055fd8 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 3 Nov 2026 01:53:38 -0500 Subject: [PATCH 3/3] docs: keep each new stamp's date and recheck trigger on one line The stamps at adjudication.md, draft-goal-condition and design split "as of" from its date or from the trigger across lines, so the stamp checker could not see the date as a stamp. Each now opens its own line with "as of ; recheck when". Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Vcupom3BKF6QuC5U3sRJPj --- .../skills/audit-dead-code/context/adjudication.md | 4 ++-- plugins/planning/skills/design/SKILL.md | 5 +++-- plugins/planning/skills/draft-goal-condition/SKILL.md | 4 ++-- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/plugins/code-tidying/skills/audit-dead-code/context/adjudication.md b/plugins/code-tidying/skills/audit-dead-code/context/adjudication.md index 057701ab13d..37fb8aab8e9 100644 --- a/plugins/code-tidying/skills/audit-dead-code/context/adjudication.md +++ b/plugins/code-tidying/skills/audit-dead-code/context/adjudication.md @@ -29,8 +29,8 @@ strings), then the config surfaces, then the framework-registration patterns for language. Stop at the first piece of real evidence. The optional `LSP` assist is one more source, never a substitute. What `findReferences` returns: -[LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior), as of -2026-11-03; recheck when that section changes what `findReferences` returns. +[LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior), +as of 2026-11-03; recheck when that section changes what `findReferences` returns. ## Verdict rules diff --git a/plugins/planning/skills/design/SKILL.md b/plugins/planning/skills/design/SKILL.md index f8e95ea9779..cb3c10c2948 100644 --- a/plugins/planning/skills/design/SKILL.md +++ b/plugins/planning/skills/design/SKILL.md @@ -389,8 +389,9 @@ it, emit the plainest correct form of the dialect. The typed artifact is produce for the round after it resolves. Render a round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`; unexpanded or empty means off) is on and the round is independent questions that fit one `AskUserQuestion` call (the per-call question limit: - , as of 2026-10-11; - recheck when that section changes the per-call question limit). Inline prose otherwise + , + as of 2026-10-11; recheck when that section changes the per-call question limit). Inline prose + otherwise - **Grounding steps.** Ground a consequential recommendation in the affected code plus its consumers and in external research that reads official docs first, routed to `/discovery:explore` and `/discovery:research` if enabled. A recommendation that changes is diff --git a/plugins/planning/skills/draft-goal-condition/SKILL.md b/plugins/planning/skills/draft-goal-condition/SKILL.md index 4b48e8631b3..862b46c8b6a 100644 --- a/plugins/planning/skills/draft-goal-condition/SKILL.md +++ b/plugins/planning/skills/draft-goal-condition/SKILL.md @@ -127,8 +127,8 @@ defers until the docs are reachable. Never finalize a draft on a shape or limit Every claim in the condition must be something Claude's own output in the transcript can demonstrate. Avoid conditions the transcript cannot show (subjective quality, external state Claude never surfaces). What the evaluator reads: -[How evaluation works](https://code.claude.com/docs/en/goal#how-evaluation-works), as of -2026-11-03; recheck when that section changes what the evaluator receives or can call. +[How evaluation works](https://code.claude.com/docs/en/goal#how-evaluation-works), +as of 2026-11-03; recheck when that section changes what the evaluator receives or can call. Structure the draft to the shape Step 1 read off the live page; this file does not restate its elements. Keep each prescribed element separately identifiable, so Step 3's tightening pass can