From 4033feb62eadf3e06b54e804948e162b7644da39 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:45:18 -0500 Subject: [PATCH 1/7] docs: replace restated upstream facts with pointers in ten plugins Rewrite passages in actionlint, architecture, context7, improvement, review, bash-format, go-format, kindle-dedrm, machine-health and miro that restated a vendor fact. Each keeps this repository's own decision and points at the live upstream section with an as-of date and a recheck trigger, or drops the sentence where nothing depends on it. One changelog fragment per plugin. The machine-health User Path 2047 limit stays as written: no Microsoft page documents that limit, so there is no owner to point at. Refs: #12697 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015te8Cr8u7uFJG4tdeUACLz --- ...stated-upstream-facts-pointers-9e599370.md | 12 ++++++ ...stated-upstream-facts-pointers-3acb239e.md | 12 ++++++ ...stated-upstream-facts-pointers-4d02a42d.md | 10 +++++ ...stated-upstream-facts-pointers-6a9194f5.md | 10 +++++ ...stated-upstream-facts-pointers-81bf9f5e.md | 13 +++++++ ...stated-upstream-facts-pointers-6d183912.md | 10 +++++ ...stated-upstream-facts-pointers-2f3b9d60.md | 10 +++++ ...stated-upstream-facts-pointers-52f16bb4.md | 10 +++++ ...stated-upstream-facts-pointers-8aaca3e6.md | 10 +++++ ...stated-upstream-facts-pointers-1f29181d.md | 12 ++++++ plugins/actionlint/README.md | 14 ++++--- plugins/actionlint/skills/setup/SKILL.md | 4 +- .../skills/map-containers/SKILL.md | 6 ++- .../architecture/skills/map-context/SKILL.md | 6 ++- .../skills/map-landscape/SKILL.md | 14 ++++--- plugins/bash-format/README.md | 17 +++++--- plugins/context7/skills/lookup/SKILL.md | 17 +++++--- plugins/context7/skills/lookup/context/mcp.md | 13 ++++--- plugins/go-format/README.md | 25 ++++++------ .../skills/find/context/ci-health.md | 39 ++++++++++++------- plugins/kindle-dedrm/skills/manage/SKILL.md | 8 ++-- plugins/machine-health/skills/setup/SKILL.md | 22 +++++++---- plugins/miro/README.md | 16 +++++--- .../review/skills/quality-gate/context/pr.md | 25 +++++++----- .../reference/bundled-security-review.md | 8 +++- 25 files changed, 255 insertions(+), 88 deletions(-) create mode 100644 .changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md create mode 100644 .changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md create mode 100644 .changes/bash-format/docs-12697-restated-upstream-facts-pointers-4d02a42d.md create mode 100644 .changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md create mode 100644 .changes/go-format/docs-12697-restated-upstream-facts-pointers-81bf9f5e.md create mode 100644 .changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md create mode 100644 .changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md create mode 100644 .changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md create mode 100644 .changes/miro/docs-12697-restated-upstream-facts-pointers-8aaca3e6.md create mode 100644 .changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md diff --git a/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md b/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md new file mode 100644 index 00000000000..8b8a66118b9 --- /dev/null +++ b/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md @@ -0,0 +1,12 @@ +--- +bump: patch +--- + +### Changed + +- The README no longer explains why ShellCheck misbehaves under actionlint or where actionlint + finds its configuration file. It keeps the choice to turn the run-block linters off at commit + and run them in CI, and points at actionlint's ShellCheck integration and configuration file + sections, each with an as-of date and a recheck trigger. +- `setup` no longer describes how a missing `node` shows up in the transcript; the FAIL and its + reason stay. diff --git a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md new file mode 100644 index 00000000000..3b6cb0461fe --- /dev/null +++ b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md @@ -0,0 +1,12 @@ +--- +bump: patch +--- + +### Changed + +- `map-containers` and `map-context` no longer give mermaid's C4 status as the reason the + dialect key refuses mermaid; the refusal, the unset key and the no-diagram fallback stay, with a + pointer to the Mermaid C4 page. +- `map-landscape` no longer states what each dialect offers for a landscape view. It keeps that + the mermaid output is a `C4Context` diagram without a focal system and points at the + Structurizr `systemLandscape` view and the Mermaid C4 page. diff --git a/.changes/bash-format/docs-12697-restated-upstream-facts-pointers-4d02a42d.md b/.changes/bash-format/docs-12697-restated-upstream-facts-pointers-4d02a42d.md new file mode 100644 index 00000000000..676e4396691 --- /dev/null +++ b/.changes/bash-format/docs-12697-restated-upstream-facts-pointers-4d02a42d.md @@ -0,0 +1,10 @@ +--- +bump: patch +--- + +### Changed + +- The README no longer describes what `.editorconfig` and `--apply-ignore` do for shfmt, or how + ShellCheck and shfmt find their configuration. It keeps the choice to pass no style flags and + to pass `--apply-ignore`, and that configuration comes from your repository, and points at the + shfmt manual page and ShellCheck's RC FILES section. diff --git a/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md b/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md new file mode 100644 index 00000000000..842ee9fa738 --- /dev/null +++ b/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md @@ -0,0 +1,10 @@ +--- +bump: patch +--- + +### Changed + +- `lookup` and its MCP reference no longer list the MCP tools' parameters or describe them; they + keep the tool-list check and the tool-to-CLI mapping and point at Context7's MCP Tools section. +- The Windows Git Bash gotcha keeps the `MSYS_NO_PATHCONV=1` prefix rule and points at MSYS2's + automatic path conversion section instead of describing the rewrite. diff --git a/.changes/go-format/docs-12697-restated-upstream-facts-pointers-81bf9f5e.md b/.changes/go-format/docs-12697-restated-upstream-facts-pointers-81bf9f5e.md new file mode 100644 index 00000000000..9b9a365dd19 --- /dev/null +++ b/.changes/go-format/docs-12697-restated-upstream-facts-pointers-81bf9f5e.md @@ -0,0 +1,13 @@ +--- +bump: patch +--- + +### Changed + +- The README no longer spells out Go's generated-code marker or what `goimports` knows about + it; the skip-generated-files rule and the header-before-marker case stay, with a pointer to the + `go generate` section. +- The `goimports` requirement no longer carries the install command or the toolchain and + `GOPATH` notes. It keeps that `goimports` must be on `PATH`, is never downloaded, and that the + batch row skips and the SessionStart probe reports when it is absent, with a pointer to the + `goimports` docs. diff --git a/.changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md b/.changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md new file mode 100644 index 00000000000..97499cb406e --- /dev/null +++ b/.changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md @@ -0,0 +1,10 @@ +--- +bump: patch +--- + +### Changed + +- The `find` CI-health context no longer states the REST `per_page` cap, what `run_attempt`, + `run_started_at` and `created_at` mean, or which filters and options the GitHub MCP tools lack. + It keeps the window and paging rules, the three fields per run and the MCP-path rule, and + points at the workflow-runs REST sections and the GitHub MCP Server tools list. diff --git a/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md new file mode 100644 index 00000000000..11651da424d --- /dev/null +++ b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md @@ -0,0 +1,10 @@ +--- +bump: patch +--- + +### Changed + +- `manage` no longer describes how Amazon stages installers or what the cached installer does. + The rules stay: never open Kindle for PC while the block is disabled except to sync with the + keyfinder ready, never run the cached installer, delete it, and follow the + `sync-finalize.sh` logic. diff --git a/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md new file mode 100644 index 00000000000..a7056e7c36d --- /dev/null +++ b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md @@ -0,0 +1,10 @@ +--- +bump: patch +--- + +### Changed + +- `setup` no longer describes `claude plugin configure`'s install lookup, the rerun's `-s` + default, or either route's exit code and empty-string handling. It keeps passing the scope + `claude plugin list` reports and reading each route's output, and points at the + `plugin configure` and `plugin install` sections of the plugin commands reference. diff --git a/.changes/miro/docs-12697-restated-upstream-facts-pointers-8aaca3e6.md b/.changes/miro/docs-12697-restated-upstream-facts-pointers-8aaca3e6.md new file mode 100644 index 00000000000..e858e289116 --- /dev/null +++ b/.changes/miro/docs-12697-restated-upstream-facts-pointers-8aaca3e6.md @@ -0,0 +1,10 @@ +--- +bump: patch +--- + +### Changed + +- The README no longer spells out the plugin cache path layout or how Node runs TypeScript. It + keeps the step to locate the cached `launch.ts` again after an update and the choice of no + build step and no committed build output, and points at the plugin loading reference and + Node's type stripping section. diff --git a/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md b/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md new file mode 100644 index 00000000000..7e214b0a5cd --- /dev/null +++ b/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md @@ -0,0 +1,12 @@ +--- +bump: patch +--- + +### Changed + +- The `quality-gate` PR mode no longer describes how the `code-review` marketplace plugin runs + or what it and the managed service post. It keeps the gate by effect and when this mode uses + each surface, and points at the plugin's Commands section and the local review's reads-and-edits + section. +- The `security-review` bundled-command record no longer lists what gates the native command; + it keeps that the lane never depends on it and points at the commands reference. diff --git a/plugins/actionlint/README.md b/plugins/actionlint/README.md index 71e7678d44b..53395465586 100644 --- a/plugins/actionlint/README.md +++ b/plugins/actionlint/README.md @@ -21,10 +21,10 @@ It ships no rules of its own and no binary. It runs the `actionlint` already on - **A partly staged file is linted as staged.** The check reads the index, so the lint matches what the commit records. - **External run-block linters disabled (`-shellcheck= -pyflakes=`).** - actionlint's embedded-bash ShellCheck and `shell: python` pyflakes integrations are turned off. - Each spawns a subprocess per `run:` block. ShellCheck deadlocks on large blocks under the - Windows subprocess IPC path in actionlint 1.7.x. Native workflow diagnostics are unaffected; - run the full integrations in CI. + actionlint's embedded-bash ShellCheck and `shell: python` pyflakes integrations are turned off + at commit time; run the full integrations in CI. For how the integration runs, see + [actionlint checks: ShellCheck integration for `run:`](https://github.com/rhysd/actionlint/blob/main/docs/checks.md#shellcheck-integration-for-run) + (as of 2026-11-03; recheck when that section changes how ShellCheck is invoked per `run:` block). - **Opt-in end-of-turn check.** With `actionlint_end_of_turn` on, a Stop row runs the same check over the uncommitted workflow changes (untracked files included) when a turn ends and hands findings back to Claude once per turn. Nothing is rewritten. Off by default. @@ -85,8 +85,10 @@ Then verify prerequisites with `/actionlint:setup check` and register the pre-co ## Configuration -actionlint auto-discovers its own `.github/actionlint.yaml` config from your -repository when present. Two `userConfig` options tune the hooks themselves: +For actionlint's own configuration file, see +[actionlint configuration: Configuration file](https://github.com/rhysd/actionlint/blob/main/docs/config.md#configuration-file) +(as of 2026-11-03; recheck when that section changes where the file is read from). Two +`userConfig` options tune the hooks themselves: - **`actionlint_enabled`** (boolean, default `true`). Kill switch for the plugin's Claude Code hooks (the end-of-turn row and the SessionStart probe). It does not govern the git pre-commit diff --git a/plugins/actionlint/skills/setup/SKILL.md b/plugins/actionlint/skills/setup/SKILL.md index c3b65f9f18a..7ffacefd4b8 100644 --- a/plugins/actionlint/skills/setup/SKILL.md +++ b/plugins/actionlint/skills/setup/SKILL.md @@ -59,8 +59,8 @@ enabled-gate. 1. **Bash version.** Check against the hook's documented floor (README Requirements). 2. **`node`.** The pre-computed `node` row. FAIL if absent, even when the toggle is off: every hook row launches through `node hooks/exec-bash.mjs`, so the hooks do not launch and the - session-start probe does not run. The hooks cannot report this themselves; the transcript shows - a hook error notice. Probed here through Bash, which works without the launcher. + session-start probe does not run. The hooks cannot report this themselves. Probed here + through Bash, which works without the launcher. 3. **`actionlint`.** The pre-computed `actionlint` row. FAIL if absent: the pre-commit entry then fails the commit of an agent with the install command and gives a person a notice, and the end-of-turn check does nothing. diff --git a/plugins/architecture/skills/map-containers/SKILL.md b/plugins/architecture/skills/map-containers/SKILL.md index cf4beedc132..58519adc737 100644 --- a/plugins/architecture/skills/map-containers/SKILL.md +++ b/plugins/architecture/skills/map-containers/SKILL.md @@ -295,9 +295,13 @@ hand-written; the publish destination comes from the `medium` cascade key. Proce earlier stage takes that stage's image. - **The dialect key is `diagram_dialect.system`, and it has no default.** Every C4 view of the code reads the key the authoring-formats convention assigns to C4 system views, the same key `/planning:design` reads for its design container view. It refuses - mermaid because mermaid C4 is experimental. Unset, `containers.md` carries the tables and no diagram, + mermaid. Unset, `containers.md` carries the tables and no diagram, and the report says no view was emitted. The key is documented in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. + - **Pointer**: for what mermaid's C4 support covers, see + [Mermaid: C4 Diagrams](https://mermaid.js.org/syntax/c4.html#c4-diagrams). + - **As of**: 2026-11-03 + - **Recheck trigger**: that page changes the status of C4 support or adds a diagram type. - **A reformatted record reads as empty unless the reader refuses it.** `render-containers.sh` exits 1 on any other shape and writes nothing. - **Configuration is untrusted text.** The assignment scanner matches it. It does not source it, diff --git a/plugins/architecture/skills/map-context/SKILL.md b/plugins/architecture/skills/map-context/SKILL.md index 8f662552f77..281171d7b8c 100644 --- a/plugins/architecture/skills/map-context/SKILL.md +++ b/plugins/architecture/skills/map-context/SKILL.md @@ -225,10 +225,14 @@ hand-written; the publish destination comes from the `medium` cascade key. Proce operator-stated `--actors` file. A non-interactive run passes no file, and the artifact says so. - **The dialect key is `diagram_dialect.system`, and it has no default.** Every C4 view of the code reads the key the authoring-formats convention assigns to - C4 system views, which refuses mermaid because mermaid C4 is experimental. An unset key is the + C4 system views, which refuses mermaid. An unset key is the common case: the run still writes `context.json` and a `context.md` with no diagram, and the report says no view was emitted. The key is documented in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. + - **Pointer**: for what mermaid's C4 support covers, see + [Mermaid: C4 Diagrams](https://mermaid.js.org/syntax/c4.html#c4-diagrams). + - **As of**: 2026-11-03 + - **Recheck trigger**: that page changes the status of C4 support or adds a diagram type. - **Redaction keeps the shape.** Host, service kind, and an optional numeric port. A secret-only key (`Password`, `ClientSecret`, `AccountKey`, and the rest named in `redact-connection.awk`) produces no row. Loopback hosts are not external systems. Do not paste a raw value into the diff --git a/plugins/architecture/skills/map-landscape/SKILL.md b/plugins/architecture/skills/map-landscape/SKILL.md index 18dfacca83c..072c378a919 100644 --- a/plugins/architecture/skills/map-landscape/SKILL.md +++ b/plugins/architecture/skills/map-landscape/SKILL.md @@ -235,12 +235,14 @@ hand-written; the publish destination comes from the `medium` cascade key. Proce ## Gotchas -- **The two dialects are not symmetric, and mermaid is the loose one.** Structurizr has a dedicated - `systemLandscape` view type. Mermaid has no landscape diagram type, so the mermaid output - is a `C4Context` diagram used without a focal system. The mermaid-C4 experimental fact and - the recheck trigger (experimental banner drops, or mermaid documents a dedicated landscape - type) live in `${CLAUDE_PLUGIN_ROOT}/reference/config.md` under C4 dialect surfaces. This - skill does not carry a second stamp. +- **The two dialects are not symmetric, and mermaid is the loose one.** The mermaid output is a + `C4Context` diagram used without a focal system. + - **Pointer**: for the landscape view each dialect offers, see + [Structurizr DSL: systemLandscape view](https://docs.structurizr.com/dsl/language#systemlandscape-view) + and [Mermaid: C4 Diagrams](https://mermaid.js.org/syntax/c4.html#c4-diagrams). + - **As of**: 2026-11-03 + - **Recheck trigger**: either section changes its landscape view, or mermaid documents a + dedicated landscape diagram type. - **A referenced repository is not a checked-out one, and the portfolio says so.** Under the default scope only the subject repository has probed facts. Everything else is a node with edges and an `unknown` row. That is the honest answer without `--remote`, not a gap to fill by guessing. diff --git a/plugins/bash-format/README.md b/plugins/bash-format/README.md index 9f6700c427a..b4ab551730e 100644 --- a/plugins/bash-format/README.md +++ b/plugins/bash-format/README.md @@ -29,9 +29,12 @@ for formatting. It ships no rules of its own. as a format gate would rewrite shell files to shfmt's built-in defaults. A repo whose `.editorconfig` only configures other languages (or has none) likewise leaves shell files untouched. Path-only sections like `[scripts/**]` are also excluded; use an explicit shell glob. - shfmt runs with no parser/printer flags, so your `.editorconfig` is authoritative, and with - `--apply-ignore` so an `ignore = true` section (e.g. for generated or vendored scripts) is - honored even on a single named file. + shfmt runs with no parser/printer flags and with `--apply-ignore`, so your `.editorconfig` + sets the style and an `ignore = true` section (e.g. for generated or vendored scripts) excludes + a file. For what each does, see the DESCRIPTION section and the `--apply-ignore` entry of the + [shfmt manual page](https://github.com/mvdan/sh/blob/master/cmd/shfmt/shfmt.1.scd), which the + [mvdan/sh README: shfmt](https://github.com/mvdan/sh#shfmt) section links (as of 2026-11-03; + recheck when either changes how EditorConfig options or ignore rules apply). - **Pre-existing drift is rewritten whole.** The batch payload carries no pre-edit bytes, so a file that already drifted from your style is formatted in full, as the pre-commit entry would. - **A rewrite that would change an array subscript is put back.** shfmt parses an unquoted @@ -51,9 +54,11 @@ for formatting. It ships no rules of its own. read with `--to-json`, or with `-tojson` on a shfmt older than 3.8, since 3.4 and 3.5 have no `--to-json`. When the tree cannot be read, the rewrite is put back, because an unchecked rewrite may have changed a key. A file shfmt leaves unchanged reads no tree and costs no extra process. -- **Config from the consumer.** ShellCheck discovers `.shellcheckrc` by walking up from the file's - directory; shfmt reads `.editorconfig` the same way. Files under `.githooks/` (installed copies) - are skipped. +- **Config from the consumer.** Both tools read their configuration from your repository: + `.shellcheckrc` for ShellCheck and `.editorconfig` for shfmt. For how each file is found, see + [ShellCheck manual: RC FILES](https://github.com/koalaman/shellcheck/blob/master/shellcheck.1.md#rc-files) + and the shfmt manual page linked above (as of 2026-11-03; recheck when either changes where it + looks for its file). Files under `.githooks/` (installed copies) are skipped. - **Gitignored files are skipped by default in the session.** The batch row does not rewrite a file the repository gitignores, silently, since a rewrite of an ignored file has no git checkout to undo it. Set `bash_format_lint_gitignored` to `true` to act on them too. A tracked file that diff --git a/plugins/context7/skills/lookup/SKILL.md b/plugins/context7/skills/lookup/SKILL.md index d72fd269c56..439d85a050d 100644 --- a/plugins/context7/skills/lookup/SKILL.md +++ b/plugins/context7/skills/lookup/SKILL.md @@ -39,12 +39,13 @@ ctx7 library "" "" MSYS_NO_PATHCONV=1 ctx7 docs "" "" ``` -Or through the MCP server, when configured: +Or through the MCP server, when configured: `mcp__context7__resolve-library-id`, then +`mcp__context7__query-docs` with the resolved ID. -```text -mcp__context7__resolve-library-id(libraryName: "...", query: "...") -mcp__context7__query-docs(libraryId: "/org/project", query: "...") -``` +- **Pointer**: for each MCP tool's parameters, fetch + [Context7: MCP Tools](https://github.com/upstash/context7#mcp-tools) live. +- **As of**: 2026-11-03 +- **Recheck trigger**: that section renames a tool or changes which parameters it requires. - Always resolve first; the docs step rejects anything but a resolved ID, unless the user supplied one in `/org/project` form. - One concept per query; run a separate lookup per independent topic, and at most 3 lookup commands per topic. When Context7 does not cover it, answer from training knowledge and say so. @@ -78,7 +79,11 @@ never hand a `${…}` token from those files to the Bash tool. ## Gotchas -- **Windows Git Bash** rewrites `ctx7 docs /org/project` into `C:/Program Files/Git/org/project`. Always prefix `ctx7 docs`, and `ctx7 search --library /org/project`, with `MSYS_NO_PATHCONV=1`; `ctx7 library` is unaffected. Detail: [context/cli.md](context/cli.md). +- **Windows Git Bash**: always prefix `ctx7 docs`, and `ctx7 search --library /org/project`, with `MSYS_NO_PATHCONV=1`; `ctx7 library` is unaffected. Detail: [context/cli.md](context/cli.md). + - **Pointer**: for how an MSYS2-based shell rewrites a `/org/project` argument, see + [MSYS2: Automatic Unix ⟶ Windows Path Conversion](https://www.msys2.org/docs/filesystem-paths/#automatic-unix-windows-path-conversion). + - **As of**: 2026-11-03 + - **Recheck trigger**: that section changes which arguments are converted. - The CLI has no flag for content depth; for more per call, use the MCP server. - Never run `ctx7 setup`, or `ctx7 skills install` if a guide names it: this plugin owns the lookup surface, and a second copy of Upstash's `find-docs` fragments lookups and drifts on its own. - This skill retrieves library docs only. Architecture decisions and other questions that need cross-checked sources go to a research workflow. diff --git a/plugins/context7/skills/lookup/context/mcp.md b/plugins/context7/skills/lookup/context/mcp.md index 8a0df1a9e7b..8c616d9a960 100644 --- a/plugins/context7/skills/lookup/context/mcp.md +++ b/plugins/context7/skills/lookup/context/mcp.md @@ -51,12 +51,15 @@ or its as-of date changes): ## Tools exposed -| Tool | Purpose | CLI equivalent | -|---|---|---| -| `mcp__context7__resolve-library-id` | Resolve library name → `/org/project` ID | `ctx7 library ` | -| `mcp__context7__query-docs` | Fetch docs for a resolved ID | `MSYS_NO_PATHCONV=1 ctx7 docs ` | +| Tool | CLI equivalent | +|---|---| +| `mcp__context7__resolve-library-id` | `ctx7 library ` | +| `mcp__context7__query-docs` | `MSYS_NO_PATHCONV=1 ctx7 docs ` | -Both tools require a `query` argument for result ranking. Same input shape as CLI, same backend, and same output substance. Only the transport differs. +- **Pointer**: for what each tool does and the arguments it takes, fetch + [Context7: MCP Tools](https://github.com/upstash/context7#mcp-tools) live. +- **As of**: 2026-11-03 +- **Recheck trigger**: that section renames a tool or changes which arguments it requires. ## Why prefer MCP over CLI for most lookups diff --git a/plugins/go-format/README.md b/plugins/go-format/README.md index e967720a224..55c2bc03403 100644 --- a/plugins/go-format/README.md +++ b/plugins/go-format/README.md @@ -26,11 +26,14 @@ the pre-commit entry reports it. has no meaningful config-divergence axis when left unconfigured. Running it does not impose a style choice a repo hasn't made, the same reasoning that makes `gofmt` itself safe to run unconditionally. -- **Skips generated files.** A file whose leading comment/blank-line block contains Go's - canonical `// Code generated ... DO NOT EDIT.` marker is left untouched, in the session and at - commit. This includes files where a copyright/license header (a `//` or `/* */` block) precedes - the marker, common for `addlicense`/`goheader` output. `goimports` itself has no awareness of - that convention, so the plugin adds the guard itself. +- **Skips generated files.** A file whose leading comment/blank-line block carries Go's + generated-code marker is left untouched, in the session and at commit. This includes files + where a copyright/license header (a `//` or `/* */` block) precedes the marker, common for + `addlicense`/`goheader` output. The plugin applies this guard itself. For the marker's exact + form, see + [go command: Generate Go files by processing source](https://pkg.go.dev/cmd/go#hdr-Generate_Go_files_by_processing_source) + (as of 2026-11-03; recheck when that section changes the marker's pattern or where it must + appear). - **Leaves gitignored files alone.** By default a `.go` file the repository gitignores is not rewritten in the session, since a rewrite of an ignored file has no git checkout to undo it. A tracked file that matches an ignore pattern stays in scope. Set `go_format_lint_gitignored=true` @@ -71,14 +74,10 @@ fails with the install command, a person gets a one-line notice, and node the hooks do not start and nothing is enforced. - **jq** on `PATH`. The batch row reads the file paths with it. Absent: the row does nothing. [Install jq](https://jqlang.org/download/). -- **goimports** on `PATH`. Like `typos-format`, `goimports` has no - per-repo dependency-manager convention. It is conventionally - `go install`ed to the machine-global `$GOPATH/bin`. It is never - downloaded on the fly; if it is not present, the batch row skips the files, and the - SessionStart probe reports the gap. - [Install](https://pkg.go.dev/golang.org/x/tools/cmd/goimports): - `go install golang.org/x/tools/cmd/goimports@latest` (requires a - [Go toolchain](https://go.dev/dl/)). +- **goimports** on `PATH`. It is never downloaded on the fly; if it is not present, the batch + row skips the files, and the SessionStart probe reports the gap. For how to install it, see + [goimports: Overview](https://pkg.go.dev/golang.org/x/tools/cmd/goimports#pkg-overview) + (as of 2026-11-03; recheck when that page changes its install command). - **`go` on `PATH` (optional).** Used only to resolve the `-local` grouping prefix (`go list -m`). Absent: `goimports` still formats and fixes imports, just without the `-local` grouping (its plain default behavior). diff --git a/plugins/improvement/skills/find/context/ci-health.md b/plugins/improvement/skills/find/context/ci-health.md index 0de47b64c01..d75b8a5cdff 100644 --- a/plugins/improvement/skills/find/context/ci-health.md +++ b/plugins/improvement/skills/find/context/ci-health.md @@ -63,17 +63,25 @@ parameters it applies to. Use the documented `created` date filter: each window separately with `created=..`. - Write the window bounds as **literal ISO dates** you compute yourself. Do not shell out to date arithmetic, whose flags are dialect-split. -- `per_page` caps at 100 (values above are silently clamped). If a window's `total_count` - exceeds 100, either narrow the window or fetch the few extra pages *within* that window. - Shallow pages inside a bounded window are fine; an unbounded page walk across the whole - history is what the cap breaks. +- If a window's `total_count` exceeds one page, either narrow the window or fetch the few extra + pages *within* that window. Shallow pages inside a bounded window are fine; never walk pages + across the whole history. + - **Pointer**: for the page-size limit, read the `per_page` parameter in + [List workflow runs for a repository](https://docs.github.com/en/rest/actions/workflow-runs#list-workflow-runs-for-a-repository). + - **As of**: 2026-11-03 + - **Recheck trigger**: that section changes the `per_page` maximum. ## Metrics Per completed run, three fields do all the work: `conclusion` (failure ratio), `run_attempt` -(retry detection: a run with `run_attempt > 1` was re-run), and -`updated_at − run_started_at` (wall duration of the latest attempt; use `run_started_at`, not -`created_at`, which includes queue time). +(retry detection: `run_attempt > 1`), and `updated_at − run_started_at` (wall duration; use +`run_started_at`, not `created_at`). + +- **Pointer**: for what each field records, read the response schema of + [Get a workflow run](https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run). +- **As of**: 2026-11-03 +- **Recheck trigger**: that schema renames or drops `run_attempt`, `run_started_at` or + `created_at`. Via `gh` (one window; repeat per window): @@ -95,14 +103,19 @@ gh api "repos/$OWNER/$REPO/actions/runs?created=2026-07-01..2026-07-07&per_page= | @tsv' ``` -Via the GitHub MCP tools, the per-run fields are the same (`conclusion`, `run_attempt`, -`run_started_at`, `updated_at`) but the window mechanics are NOT: the `actions_list` tooling -exposes no `created` date filter, so date-windowed iteration is unreachable through it. On the -MCP path, read the most recent page(s) only, cite the covered span verbatim ("last N runs, +Via the GitHub MCP tools, read the same per-run fields (`conclusion`, `run_attempt`, +`run_started_at`, `updated_at`), but do not window by date. On the MCP path, read the most +recent page(s) only, cite the covered span verbatim ("last N runs, <oldest>..<newest>"), and record the uncovered windows as a `gap:` line. Never page deep to reach them and never present a recent-page sample as full-window coverage. Full date-window -iteration needs the REST call above (`gh api` or an equivalent raw-request path). Use -`get_job_logs` (failed-jobs-only option) when a candidate needs "why is CI red" specifics. +iteration uses the REST call above (`gh api` or an equivalent raw-request path). Use +`get_job_logs` when a candidate needs "why is CI red" specifics. + +- **Pointer**: for the filters `actions_list` takes and the options `get_job_logs` offers, fetch + [GitHub MCP Server: Tools](https://github.com/github/github-mcp-server#tools) live. +- **As of**: 2026-11-03 +- **Recheck trigger**: `actions_list` documents a date filter, or `get_job_logs` changes its + options. Derived signals: diff --git a/plugins/kindle-dedrm/skills/manage/SKILL.md b/plugins/kindle-dedrm/skills/manage/SKILL.md index ccfca317e76..a73339cd2d4 100644 --- a/plugins/kindle-dedrm/skills/manage/SKILL.md +++ b/plugins/kindle-dedrm/skills/manage/SKILL.md @@ -38,11 +38,11 @@ Smart auto-detect when action is empty: read pre-computed context, classify stat Apply across every action. Violating any risks losing the working 2.8.0 setup or stranding the user with an upgraded Kindle that can't be downgraded without re-extracting from a different machine. -- **Never open Kindle for PC while the firewall block is disabled UNLESS the user is actively syncing new books AND has the keyfinder ready to run immediately afterward.** Amazon stages 2.9.x installers aggressively; one open window with internet access is enough to cache an installer that auto-runs on next launch. -- **Never run the cached installer at `%LOCALAPPDATA%\Amazon\Kindle\updates\KindleForPC-installer.exe`.** This is the auto-update payload that breaks key extraction. Delete it whenever it appears. +- **Never open Kindle for PC while the firewall block is disabled UNLESS the user is actively syncing new books AND has the keyfinder ready to run immediately afterward.** +- **Never run the cached installer at `%LOCALAPPDATA%\Amazon\Kindle\updates\KindleForPC-installer.exe`.** Delete it whenever it appears. - **Never recommend `--no-confirm` flags or batch-confirm cleanup.** Each reversal is independent; some harder to redo than others (re-pinning Kindle 2.8.0 is easy; re-syncing 50 books isn't). This holds when the user asks for "yes to all": never write, run or hand over a script or command that pipes `yes`, skips the prompts or loops over the reversals without asking. - **Never send any of these scripts, keys, or extracted files outside the user's machine.** Personal-use scope only. -- **The cached installer + firewall race is real:** if user reports "an installer popped up when I opened Kindle," immediately follow scripts/sync-finalize.sh delete logic. Do not let the installer complete. +- **An installer that appears is deleted at once:** if user reports "an installer popped up when I opened Kindle," immediately follow scripts/sync-finalize.sh delete logic. Do not let the installer complete. ## Action: setup @@ -67,7 +67,7 @@ Sequence: 1. Verify state via status.sh. Abort if firewall rule absent or ICACLS deny missing (run `setup` first). 2. **Disable firewall block** (`scripts/firewall.ps1 disable`). 3. **User opens Kindle for PC, syncs, double-clicks new books, quits Kindle.** Agent cannot drive GUI; pause for user confirmation. -4. **Delete any newly-staged installer** at `%LOCALAPPDATA%\Amazon\Kindle\updates\*` (`scripts/sync-finalize.sh`). ICACLS deny prevents *future* writes but doesn't stop one that lands during the brief firewall-disabled window. +4. **Delete any newly-staged installer** at `%LOCALAPPDATA%\Amazon\Kindle\updates\*` (`scripts/sync-finalize.sh`). 5. **Re-enable firewall block** (`scripts/firewall.ps1 enable`). 6. **Re-run keyfinder** (`~/Tools/Kindle_Key_Finder/Run_keyfinder_admin.vbs`). Saved config auto-loads; tool processes only new books. 7. **Verify new EPUBs** under Calibre Library. diff --git a/plugins/machine-health/skills/setup/SKILL.md b/plugins/machine-health/skills/setup/SKILL.md index cf8b904608d..adaac8d245b 100644 --- a/plugins/machine-health/skills/setup/SKILL.md +++ b/plugins/machine-health/skills/setup/SKILL.md @@ -271,14 +271,20 @@ Reject an argument targeting an unknown check id, remediation or muted key with (repeatable per key). Against an already-installed plugin it prints `already installed` and still writes the value. Do **not** uninstall to reconfigure: that drops the plugin's entire stored `pluginConfigs` entry, resetting every option in the README's Options reference to its - manifest default. Either route stores the value in user settings. `claude plugin configure` - has no scope flag and finds only an install visible from the working directory. For the rerun, - `-s` defaults to `user`; pass the scope `claude plugin list` reports, and run from that - project's directory for a `project`/`local` scope, or the rerun adds a second install record at - the scope passed and enables the plugin there; from the home directory pass `user`. Check each - route's own failure signal: `claude plugin configure` rejects a bad value with exit 1 and saves - nothing, but stores an empty string as `""`; the rerun prints a warning for a rejected value yet - exits 0, so read its output. This skill never writes user settings or `pluginConfigs`. Afterwards rerun + manifest default. Run either route from the project the plugin is installed in. For the rerun, + always pass `-s` with the scope `claude plugin list` reports; from the home directory pass + `user`. Read each route's output, not only its exit code, to tell a saved value from a + rejected one. + - **Pointer**: for how each route resolves the install, its scope default, and what it prints + and exits with on a rejected value, fetch + [Plugin commands reference: plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) + and [plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) + live. + - **As of**: 2026-11-03 + - **Recheck trigger**: either section changes how it finds an install, its scope default, or + its output or exit code on a rejected value. + + This skill never writes user settings or `pluginConfigs`. Afterwards rerun `check` in a **fresh session**. The rendered `${user_config.*}` and each hook's `CLAUDE_PLUGIN_OPTION_*` are fixed at session start, so a same-session `check` still reports the OLD value; report the observed effective value, never an unobserved change. diff --git a/plugins/miro/README.md b/plugins/miro/README.md index a8cbc9ebdfc..553e23fbb4b 100644 --- a/plugins/miro/README.md +++ b/plugins/miro/README.md @@ -90,10 +90,11 @@ tool call with the configure instruction, which is why the recipe below disables and launches a different server process instead. 1. Enable the plugin. -2. Locate this plugin's cached server entry point. Claude Code copies an installed plugin into a - version-keyed cache directory, - `~/.claude/plugins/cache//miro//server/src/launch.ts`. The - exact path changes on every `miro` update, so re-check it after one. +2. Locate this plugin's cached server entry point, `server/src/launch.ts` inside the installed + `miro` plugin's cache directory, and locate it again after every `miro` update. For where + that directory is, see + [Plugin loading reference: Find plugins on disk](https://code.claude.com/docs/en/plugins/loading#find-plugins-on-disk) + (as of 2026-11-03; recheck when that section changes the cache path layout). 3. Add a **user-scope** stdio MCP server whose command wraps that path with `vault-exec`. A directly configured server does not receive `CLAUDE_PLUGIN_DATA`, so pass it with `-e`; the plugin's data directory is `~/.claude/plugins/data/miro-`: @@ -149,8 +150,11 @@ on Node ≥ 24. Cross-platform, no per-OS path divergence at the stdio boundary. definitions are thin wrappers over the [`@mirohq/miro-api`](https://www.npmjs.com/package/@mirohq/miro-api) client; the request/response and error-shaping logic lives in `server/src/`. -The TypeScript in `server/src/` is what runs: Node strips the types at load, so there is no -build step and no committed build output. The repo follows the +The TypeScript in `server/src/` is what runs: there is no build step and no committed build +output. For how Node runs a `.ts` file, see +[Node.js: Type stripping](https://nodejs.org/api/typescript.html#type-stripping) (as of +2026-11-03; recheck when that section changes which TypeScript syntax runs without a flag). The +repo follows the [on-demand dependencies convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/on-demand-dependencies/README.md): no third-party code is committed. `server/src/launch.ts` installs the runtime dependencies on first launch and then starts `index.ts`: diff --git a/plugins/review/skills/quality-gate/context/pr.md b/plugins/review/skills/quality-gate/context/pr.md index f4509aecb8b..536de7e758f 100644 --- a/plugins/review/skills/quality-gate/context/pr.md +++ b/plugins/review/skills/quality-gate/context/pr.md @@ -9,9 +9,13 @@ marketplace plugin, plus two that ship with Claude Code itself. They share a nam routinely conflated; they are distinct: - **`code-review` marketplace plugin**: `/code-review:code-review`, installed from the - `claude-plugins-official` marketplace like any other plugin. A PR is its only target: it runs - parallel review agents with confidence scoring against that PR, then posts the surviving findings - back as a PR comment as its final step. It has no mode that returns them to the session instead. + `claude-plugins-official` marketplace like any other plugin. This mode never runs it as a + read-only pass: it is a gated surface (Mutation gate below), dispatched only on explicit opt-in. + - **Pointer**: for what the plugin targets and where its findings go, see + [code-review plugin: Commands](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-review#commands). + - **As of**: 2026-11-03 + - **Recheck trigger**: that section adds a target other than a PR, or a mode that returns + findings to the session without posting. - **Bundled `/code-review` command**: invoked with no plugin namespace, and never assumed present (settings, the host, and the environment decide whether it resolves). Passing a PR as its target reviews that PR locally and reports into the session. Some of its arguments edit the working @@ -40,12 +44,15 @@ the bundled-skill list. **Mutation gate.** The gate is by effect, not by flag name. It covers the plugin unconditionally, the managed service, and any bundled `/code-review` invocation whose arguments, as read live at the -pointer above, edit the working tree or post to the PR. Every -`/code-review:code-review` run ends by posting its findings as a PR comment, and triggering the -managed service posts a full review; both violate the review modes' report-only contract, as does -any bundled invocation that posts or edits. Dispatch any gated surface only on explicit user opt-in -("post the review comment", "apply the fixes"), otherwise skip and name the skip in the review -report. +pointer above, edit the working tree or post to the PR. A surface that posts to the PR or edits the +working tree violates the review modes' report-only contract. Dispatch any gated surface only on +explicit user opt-in ("post the review comment", "apply the fixes"), otherwise skip and name the +skip in the review report. + +- **Pointer**: for what the bundled command's run reads and edits, see + [code-review: What the review reads and edits](https://code.claude.com/docs/en/code-review-local#what-the-review-reads-and-edits). +- **As of**: 2026-11-03 +- **Recheck trigger**: that section changes which arguments edit the working tree or post findings. A bundled `/code-review ` whose arguments only report into the session is **not** gated: it writes nothing to the PR or the working tree, so it stays available as a read-only option diff --git a/plugins/review/skills/security-review/reference/bundled-security-review.md b/plugins/review/skills/security-review/reference/bundled-security-review.md index bbaf268948a..fc9c5d07eb7 100644 --- a/plugins/review/skills/security-review/reference/bundled-security-review.md +++ b/plugins/review/skills/security-review/reference/bundled-security-review.md @@ -27,8 +27,12 @@ monitoring routes to them, not here. ## Presence -The native command is gated by its backing plugin's availability, `skillOverrides`, the host -surface, and the environment. Nothing in this lane depends on it: the CI wrapper never invokes it. +Nothing in this lane depends on the native command: the CI wrapper never invokes it. + +- **Pointer**: for what decides whether the command is present, see the `/security-review` row of + [commands: All commands](https://code.claude.com/docs/en/commands#all-commands). +- **As of**: 2026-11-03 +- **Recheck trigger**: that row changes what the command needs to run. ## Extraction record From 4fd79a520659874d31d49f08147b449c17359075 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:53:31 -0500 Subject: [PATCH 2/7] docs: drop more restated upstream facts in four plugins machine-health: the Windows check catalog keeps the User Path 2047 CRIT threshold as this audit's own and drops the System Properties editor explanation. setup no longer states what the install rerun prints against an installed plugin or when a saved value takes effect, and points at the plugin manifest reference instead. architecture: reference/config.md no longer calls mermaid C4 experimental (the Mermaid C4 page no longer says so) or restates the recheck trigger; it points at the authoring-formats convention. actionlint: setup no longer states where actionlint finds its config file and points at actionlint's configuration file section. kindle-dedrm: manage no longer names the version Amazon stages. Each plugin's existing changelog fragment is amended. Refs: #12697 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015te8Cr8u7uFJG4tdeUACLz --- ...stated-upstream-facts-pointers-9e599370.md | 2 ++ ...stated-upstream-facts-pointers-3acb239e.md | 2 ++ ...stated-upstream-facts-pointers-2f3b9d60.md | 3 ++- ...stated-upstream-facts-pointers-52f16bb4.md | 5 +++++ plugins/actionlint/skills/setup/SKILL.md | 14 +++++++------ plugins/architecture/reference/config.md | 5 ++--- plugins/kindle-dedrm/skills/manage/SKILL.md | 2 +- .../audit/reference/windows/check-catalog.md | 5 ++--- plugins/machine-health/skills/setup/SKILL.md | 21 +++++++++++-------- 9 files changed, 36 insertions(+), 23 deletions(-) diff --git a/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md b/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md index 8b8a66118b9..7d867a6adf2 100644 --- a/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md +++ b/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md @@ -10,3 +10,5 @@ bump: patch sections, each with an as-of date and a recheck trigger. - `setup` no longer describes how a missing `node` shows up in the transcript; the FAIL and its reason stay. +- `setup` no longer states where actionlint finds its config file. The check still reports + whether one exists, as INFO, and points at actionlint's configuration file section. diff --git a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md index 3b6cb0461fe..63ed266fa2f 100644 --- a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md +++ b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md @@ -10,3 +10,5 @@ bump: patch - `map-landscape` no longer states what each dialect offers for a landscape view. It keeps that the mermaid output is a `C4Context` diagram without a focal system and points at the Structurizr `systemLandscape` view and the Mermaid C4 page. +- `reference/config.md` no longer calls mermaid C4 experimental or restates the recheck + trigger; it points at the authoring-formats convention that holds both. diff --git a/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md index 11651da424d..fa947c67905 100644 --- a/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md +++ b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md @@ -4,7 +4,8 @@ bump: patch ### Changed -- `manage` no longer describes how Amazon stages installers or what the cached installer does. +- `manage` no longer describes how Amazon stages installers, which version it stages, or what + the cached installer does. The rules stay: never open Kindle for PC while the block is disabled except to sync with the keyfinder ready, never run the cached installer, delete it, and follow the `sync-finalize.sh` logic. diff --git a/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md index a7056e7c36d..8e8cb6ecb33 100644 --- a/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md +++ b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md @@ -8,3 +8,8 @@ bump: patch default, or either route's exit code and empty-string handling. It keeps passing the scope `claude plugin list` reports and reading each route's output, and points at the `plugin configure` and `plugin install` sections of the plugin commands reference. +- `setup` no longer describes what the install rerun prints against an installed plugin or when + a saved value takes effect. It keeps rerunning `check` in a fresh session and points at the + manifest reference's saved-value section. +- The Windows check catalog's environment and PATH health entry no longer explains the User Path `CRIT` threshold with + a claim about the System Properties editor; 2047 stays as this audit's own threshold. diff --git a/plugins/actionlint/skills/setup/SKILL.md b/plugins/actionlint/skills/setup/SKILL.md index 7ffacefd4b8..616db617018 100644 --- a/plugins/actionlint/skills/setup/SKILL.md +++ b/plugins/actionlint/skills/setup/SKILL.md @@ -29,8 +29,8 @@ A row reading `[shell command execution disabled by policy]` carries no result: Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. The only consumer-project files this plugin owns are its git-hook -entry copies, which `apply install-git-hooks` writes. actionlint auto-discovers its own optional -config from the repository, and the tunables are the native `userConfig` options +entry copies, which `apply install-git-hooks` writes. actionlint's own config file belongs to +the repository, not this plugin, and the tunables are the native `userConfig` options (`actionlint_enabled` and `actionlint_end_of_turn`). Every prerequisite is a `PATH` binary the plugin never bundles, and the plugin never installs system packages, so `apply` is guidance-and-verify with that one write path. It never modifies user settings or the plugin @@ -64,10 +64,12 @@ enabled-gate. 3. **`actionlint`.** The pre-computed `actionlint` row. FAIL if absent: the pre-commit entry then fails the commit of an agent with the install command and gives a person a notice, and the end-of-turn check does nothing. -4. **actionlint config.** INFO: actionlint auto-discovers an optional - `.github/actionlint.yaml` from the repository when present. It is not required. actionlint - runs with its built-in defaults without one. Report whether one exists for the reader's - awareness; its absence is not a FAIL. +4. **actionlint config.** INFO: report whether the repository has an actionlint config file, + for the reader's awareness. This plugin does not require one, so its absence is not a FAIL. + - **Pointer**: for the file names and where actionlint looks for them, see + [actionlint configuration: Configuration file](https://github.com/rhysd/actionlint/blob/main/docs/config.md#configuration-file). + - **As of**: 2026-11-03 + - **Recheck trigger**: that section changes the file names or where the file is read from. 5. **Hook toggles.** Report the effective `actionlint_enabled` value: `${user_config.actionlint_enabled}` (unexpanded or empty means default `true`; any value other than `true` disables the Claude Code hooks). Also report `actionlint_end_of_turn`: diff --git a/plugins/architecture/reference/config.md b/plugins/architecture/reference/config.md index ee0707cc576..04ef07d6f15 100644 --- a/plugins/architecture/reference/config.md +++ b/plugins/architecture/reference/config.md @@ -109,11 +109,10 @@ unkeyed rule for those shapes, the one `/planning:design` applies to its `sequen flows. Neither emits mermaid C4. `landscape_dialect` keeps its mermaid default: it predates this decision, and the convention gives -a landscape no key. The mermaid-C4 experimental fact and its recheck trigger live in the +a landscape no key. The record of mermaid's C4 support and its recheck trigger live in the authoring-formats convention ([Why mermaid is not offered for the system key](../../../docs/contracts/authoring-formats/README.md#why-mermaid-is-not-offered-for-the-system-key)). -This document does not carry a second stamp. That trigger fires when the experimental banner -drops or when mermaid documents a dedicated landscape type. On firing, re-derive whether this +This document does not carry a second stamp. When that trigger fires, re-derive whether this key's mermaid default should change and whether `/architecture:map-landscape`'s mermaid output should use a dedicated landscape type instead of a `C4Context` diagram without a focal system, and record the outcomes in this plugin's `CHANGELOG.md`. diff --git a/plugins/kindle-dedrm/skills/manage/SKILL.md b/plugins/kindle-dedrm/skills/manage/SKILL.md index a73339cd2d4..41eca2c8601 100644 --- a/plugins/kindle-dedrm/skills/manage/SKILL.md +++ b/plugins/kindle-dedrm/skills/manage/SKILL.md @@ -72,7 +72,7 @@ Sequence: 6. **Re-run keyfinder** (`~/Tools/Kindle_Key_Finder/Run_keyfinder_admin.vbs`). Saved config auto-loads; tool processes only new books. 7. **Verify new EPUBs** under Calibre Library. -If user reports a cached installer popped up during step 3, that's expected. Amazon staged 2.9.x. Delete it via step 4 immediately and verify Kindle.exe still reports 2.8.0.70980. +If user reports a cached installer popped up during step 3, delete it via step 4 immediately and verify Kindle.exe still reports 2.8.0.70980. ## Action: update diff --git a/plugins/machine-health/skills/audit/reference/windows/check-catalog.md b/plugins/machine-health/skills/audit/reference/windows/check-catalog.md index f0fbfa0d494..1ea08a13d20 100644 --- a/plugins/machine-health/skills/audit/reference/windows/check-catalog.md +++ b/plugins/machine-health/skills/audit/reference/windows/check-catalog.md @@ -744,8 +744,7 @@ All checks emit the schema in `reference/shared/output-schema.md`, and dot-sourc ``` - **Severity rubric:** - - `CRIT`: User Path length ≥ 2047 (legacy System Properties editor ceiling; further - appends are silently discarded). + - `CRIT`: User Path length ≥ 2047, this audit's own threshold. - `WARN` when any of these hold: User Path length ≥ 1800; User Path value kind is `REG_SZ` (`String`) rather than `REG_EXPAND_SZ` (`ExpandString`); `DISABLE_AUTOUPDATER` set to a truthy @@ -765,7 +764,7 @@ All checks emit the schema in `reference/shared/output-schema.md`, and dot-sourc values. Shadowing uses the process `$env:PATH` as the live search order and labels each entry `user` / `machine` / `both` / `unknown` from membership in the persisted Path lists. Persisted Path is read without expanding `%VAR%` tokens so `user_path_length` - measures the stored string (legacy-editor ceiling). Directory existence and scope + measures the stored string. Directory existence and scope classification expand those tokens first. Otherwise stock Machine Path entries such as a `%SystemRoot%` system32 directory would false-positive as missing and be labeled `unknown`. The check does not attribute a vendor, decide whether `WindowsApps` diff --git a/plugins/machine-health/skills/setup/SKILL.md b/plugins/machine-health/skills/setup/SKILL.md index adaac8d245b..06e625ffcdc 100644 --- a/plugins/machine-health/skills/setup/SKILL.md +++ b/plugins/machine-health/skills/setup/SKILL.md @@ -268,26 +268,29 @@ Reject an argument targeting an unknown check id, remediation or muted key with Headless fallback, for a Claude Code release without `plugin configure`: rerun `claude plugin install machine-health@ -s --config report_dir=` - (repeatable per key). Against an already-installed plugin it prints `already installed` and - still writes the value. Do **not** uninstall to reconfigure: that drops the plugin's entire + (repeatable per key). Do **not** uninstall to reconfigure: that drops the plugin's entire stored `pluginConfigs` entry, resetting every option in the README's Options reference to its manifest default. Run either route from the project the plugin is installed in. For the rerun, always pass `-s` with the scope `claude plugin list` reports; from the home directory pass `user`. Read each route's output, not only its exit code, to tell a saved value from a rejected one. - - **Pointer**: for how each route resolves the install, its scope default, and what it prints - and exits with on a rejected value, fetch + - **Pointer**: for how each route resolves the install, its scope default, what it prints + against an installed plugin, and what it prints and exits with on a rejected value, fetch [Plugin commands reference: plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) and [plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) live. - **As of**: 2026-11-03 - **Recheck trigger**: either section changes how it finds an install, its scope default, or - its output or exit code on a rejected value. + its output or exit code on an installed plugin or a rejected value. - This skill never writes user settings or `pluginConfigs`. Afterwards rerun - `check` in a **fresh session**. The rendered `${user_config.*}` and each hook's - `CLAUDE_PLUGIN_OPTION_*` are fixed at session start, so a same-session `check` still reports - the OLD value; report the observed effective value, never an unobserved change. + This skill never writes user settings or `pluginConfigs`. Afterwards rerun `check` in a + **fresh session** and report the observed effective value, never an unobserved change. + - **Pointer**: for when a saved value reaches skill content and hooks, fetch + [Plugin manifest reference: Reference a saved value](https://code.claude.com/docs/en/plugins-reference#reference-a-saved-value) + and [plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) + live. + - **As of**: 2026-11-03 + - **Recheck trigger**: either section changes when a saved value takes effect. Re-running `apply` after everything is already set changes nothing and reports "already configured". From 0b3763a5fff10668af75ab2014fddce0244221cb Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:55:44 -0500 Subject: [PATCH 3/7] docs(actionlint): point at the plugin CLI docs for reconfiguration setup no longer describes what each reconfiguration route prints, exits with or stores, the rerun's -s default, or when a saved value takes effect. It keeps the steps and points at the plugin commands and manifest reference sections, matching machine-health setup. kindle-dedrm manage drops one more staged-version mention, and the architecture fragment no longer vouches for the convention's record. Refs: #12697 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015te8Cr8u7uFJG4tdeUACLz --- ...stated-upstream-facts-pointers-9e599370.md | 4 ++ ...stated-upstream-facts-pointers-3acb239e.md | 2 +- plugins/actionlint/skills/setup/SKILL.md | 38 +++++++++++-------- plugins/kindle-dedrm/skills/manage/SKILL.md | 2 +- 4 files changed, 28 insertions(+), 18 deletions(-) diff --git a/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md b/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md index 7d867a6adf2..b8a629b1867 100644 --- a/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md +++ b/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md @@ -12,3 +12,7 @@ bump: patch reason stay. - `setup` no longer states where actionlint finds its config file. The check still reports whether one exists, as INFO, and points at actionlint's configuration file section. +- `setup` no longer describes what each reconfiguration route prints, exits with or stores, the + rerun's `-s` default, or when a saved value takes effect. It keeps passing the scope + `claude plugin list` reports, reading each route's output and rerunning `check` in a fresh + session, and points at the plugin commands and manifest reference sections. diff --git a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md index 63ed266fa2f..be20d61b4ca 100644 --- a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md +++ b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md @@ -11,4 +11,4 @@ bump: patch the mermaid output is a `C4Context` diagram without a focal system and points at the Structurizr `systemLandscape` view and the Mermaid C4 page. - `reference/config.md` no longer calls mermaid C4 experimental or restates the recheck - trigger; it points at the authoring-formats convention that holds both. + trigger; it points at the authoring-formats convention's record. diff --git a/plugins/actionlint/skills/setup/SKILL.md b/plugins/actionlint/skills/setup/SKILL.md index 616db617018..79691655d1a 100644 --- a/plugins/actionlint/skills/setup/SKILL.md +++ b/plugins/actionlint/skills/setup/SKILL.md @@ -147,23 +147,29 @@ Run `check`, then for each FAIL point at the resolution. This skill installs not where `values.json` holds `{"actionlint_enabled": "true"}` (every value a string, booleans included; keys left out keep their saved values). Headless fallback, before 2.1.285: `claude plugin install actionlint@ -s --config actionlint_enabled=true` - (repeatable per key); against an already-installed plugin it prints `already installed` - **and still writes the value**. Do **not** uninstall to reconfigure: that drops this plugin's + (repeatable per key). Do **not** uninstall to reconfigure: that drops this plugin's entire stored `pluginConfigs` entry, resetting every option in the README's Options reference - to its manifest default. The value lands in user settings whichever route writes it. - `claude plugin configure` has no scope flag, so run it from the project the plugin is installed - in. For the rerun, `-s` defaults to `user`; pass the scope `claude plugin list` reports for this - plugin, and for a `project` or `local` scope run from that project's directory, so the rerun - matches the existing install record; from the home directory pass `user`. A rerun at another - scope adds an install record at that scope and enables the plugin there. Check each route's own failure signal: - `--values-stdin` rejects a bad value with exit 1 and saves nothing, but stores an empty string - as `""`; the `--config` rerun prints a warning for a rejected value yet exits 0, so read its - output. This skill never writes user settings or `pluginConfigs`. - Afterwards rerun `check` in a **fresh session**. The rendered - `${user_config.*}` is injected at skill load and each hook receives its - `CLAUDE_PLUGIN_OPTION_*` from an environment fixed at session start, so a same-session - `check` still reports the OLD value; report the observed effective value, never an - unobserved change. + to its manifest default. Run either route from the project the plugin is installed in. For the + rerun, always pass `-s` with the scope `claude plugin list` reports for this plugin; from the + home directory pass `user`. Read each route's output, not only its exit code, to tell a saved + value from a rejected one. + - **Pointer**: for how each route resolves the install, its scope default, what it prints + against an installed plugin, and what it prints and exits with on a rejected value, fetch + [Plugin commands reference: plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) + and [plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) + live. + - **As of**: 2026-11-03 + - **Recheck trigger**: either section changes how it finds an install, its scope default, or + its output or exit code on an installed plugin or a rejected value. + + This skill never writes user settings or `pluginConfigs`. Afterwards rerun `check` in a + **fresh session** and report the observed effective value, never an unobserved change. + - **Pointer**: for when a saved value reaches skill content and hooks, fetch + [Plugin manifest reference: Reference a saved value](https://code.claude.com/docs/en/plugins-reference#reference-a-saved-value) + and [plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) + live. + - **As of**: 2026-11-03 + - **Recheck trigger**: either section changes when a saved value takes effect. After pointing at a remediation, re-run the relevant `check` probe live via Bash (a pre-computed row predates the remediation, so never re-read it) and report its actual result. Never claim resolved on diff --git a/plugins/kindle-dedrm/skills/manage/SKILL.md b/plugins/kindle-dedrm/skills/manage/SKILL.md index 41eca2c8601..0e73eb3dec6 100644 --- a/plugins/kindle-dedrm/skills/manage/SKILL.md +++ b/plugins/kindle-dedrm/skills/manage/SKILL.md @@ -172,7 +172,7 @@ The skill should NEVER offer to delete the user's Calibre Library. Those are the | techy-notes.com tutorial 404s or moves | Pivot to epubor.com tutorial (secondary); update `reference/sources.md` | | Kindle for PC ships a version > 2.9.1 not in `KFXARCHIVER_TOOL_MAP` | Wait for KFXArchiver update; document in `reference/troubleshooting.md` | | Calibre's KFX Input plugin renamed in catalog | Update plugin name reference in `reference/workflow.md` | -| User reports a sync that left a 2.9.x cached installer past firewall re-enable | Tighten timing in `scripts/sync-prep.sh`. Possibly add an automatic `sync-finalize.sh` invocation when Kindle.exe quits | +| User reports a sync that left a cached installer past firewall re-enable | Tighten timing in `scripts/sync-prep.sh`. Possibly add an automatic `sync-finalize.sh` invocation when Kindle.exe quits | ## Spoke paths From 987b2d451d223dd4e5167f93000f94e932ff9696 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 3 Nov 2026 19:18:24 -0500 Subject: [PATCH 4/7] docs: keep the setup and manage skill text the evals still check Restore the actionlint setup, kindle-dedrm manage and machine-health setup skill bodies, and their changelog fragments, to their state after the first phase. The later cuts went past the issue's rows and removed text those skills' evals still expect. The machine-health fragment keeps a line for the check-catalog change, which stays. Refs: #12697 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015te8Cr8u7uFJG4tdeUACLz --- ...stated-upstream-facts-pointers-9e599370.md | 6 --- ...stated-upstream-facts-pointers-2f3b9d60.md | 3 +- ...stated-upstream-facts-pointers-52f16bb4.md | 8 ++- plugins/actionlint/skills/setup/SKILL.md | 52 ++++++++----------- plugins/kindle-dedrm/skills/manage/SKILL.md | 4 +- plugins/machine-health/skills/setup/SKILL.md | 21 ++++---- 6 files changed, 37 insertions(+), 57 deletions(-) diff --git a/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md b/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md index b8a629b1867..8b8a66118b9 100644 --- a/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md +++ b/.changes/actionlint/docs-12697-restated-upstream-facts-pointers-9e599370.md @@ -10,9 +10,3 @@ bump: patch sections, each with an as-of date and a recheck trigger. - `setup` no longer describes how a missing `node` shows up in the transcript; the FAIL and its reason stay. -- `setup` no longer states where actionlint finds its config file. The check still reports - whether one exists, as INFO, and points at actionlint's configuration file section. -- `setup` no longer describes what each reconfiguration route prints, exits with or stores, the - rerun's `-s` default, or when a saved value takes effect. It keeps passing the scope - `claude plugin list` reports, reading each route's output and rerunning `check` in a fresh - session, and points at the plugin commands and manifest reference sections. diff --git a/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md index fa947c67905..11651da424d 100644 --- a/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md +++ b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md @@ -4,8 +4,7 @@ bump: patch ### Changed -- `manage` no longer describes how Amazon stages installers, which version it stages, or what - the cached installer does. +- `manage` no longer describes how Amazon stages installers or what the cached installer does. The rules stay: never open Kindle for PC while the block is disabled except to sync with the keyfinder ready, never run the cached installer, delete it, and follow the `sync-finalize.sh` logic. diff --git a/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md index 8e8cb6ecb33..9973a490908 100644 --- a/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md +++ b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md @@ -8,8 +8,6 @@ bump: patch default, or either route's exit code and empty-string handling. It keeps passing the scope `claude plugin list` reports and reading each route's output, and points at the `plugin configure` and `plugin install` sections of the plugin commands reference. -- `setup` no longer describes what the install rerun prints against an installed plugin or when - a saved value takes effect. It keeps rerunning `check` in a fresh session and points at the - manifest reference's saved-value section. -- The Windows check catalog's environment and PATH health entry no longer explains the User Path `CRIT` threshold with - a claim about the System Properties editor; 2047 stays as this audit's own threshold. +- The Windows check catalog's environment and PATH health entry no longer explains the User Path + `CRIT` threshold with a claim about the System Properties editor; 2047 stays as this audit's own + threshold. diff --git a/plugins/actionlint/skills/setup/SKILL.md b/plugins/actionlint/skills/setup/SKILL.md index 79691655d1a..7ffacefd4b8 100644 --- a/plugins/actionlint/skills/setup/SKILL.md +++ b/plugins/actionlint/skills/setup/SKILL.md @@ -29,8 +29,8 @@ A row reading `[shell command execution disabled by policy]` carries no result: Thin check-centric setup per the uniform setup contract (`docs/plugin-philosophy.md` "Setup is explicit and repeatable" in the marketplace repository): `check` inspects and reports, `apply` resolves. The only consumer-project files this plugin owns are its git-hook -entry copies, which `apply install-git-hooks` writes. actionlint's own config file belongs to -the repository, not this plugin, and the tunables are the native `userConfig` options +entry copies, which `apply install-git-hooks` writes. actionlint auto-discovers its own optional +config from the repository, and the tunables are the native `userConfig` options (`actionlint_enabled` and `actionlint_end_of_turn`). Every prerequisite is a `PATH` binary the plugin never bundles, and the plugin never installs system packages, so `apply` is guidance-and-verify with that one write path. It never modifies user settings or the plugin @@ -64,12 +64,10 @@ enabled-gate. 3. **`actionlint`.** The pre-computed `actionlint` row. FAIL if absent: the pre-commit entry then fails the commit of an agent with the install command and gives a person a notice, and the end-of-turn check does nothing. -4. **actionlint config.** INFO: report whether the repository has an actionlint config file, - for the reader's awareness. This plugin does not require one, so its absence is not a FAIL. - - **Pointer**: for the file names and where actionlint looks for them, see - [actionlint configuration: Configuration file](https://github.com/rhysd/actionlint/blob/main/docs/config.md#configuration-file). - - **As of**: 2026-11-03 - - **Recheck trigger**: that section changes the file names or where the file is read from. +4. **actionlint config.** INFO: actionlint auto-discovers an optional + `.github/actionlint.yaml` from the repository when present. It is not required. actionlint + runs with its built-in defaults without one. Report whether one exists for the reader's + awareness; its absence is not a FAIL. 5. **Hook toggles.** Report the effective `actionlint_enabled` value: `${user_config.actionlint_enabled}` (unexpanded or empty means default `true`; any value other than `true` disables the Claude Code hooks). Also report `actionlint_end_of_turn`: @@ -147,29 +145,23 @@ Run `check`, then for each FAIL point at the resolution. This skill installs not where `values.json` holds `{"actionlint_enabled": "true"}` (every value a string, booleans included; keys left out keep their saved values). Headless fallback, before 2.1.285: `claude plugin install actionlint@ -s --config actionlint_enabled=true` - (repeatable per key). Do **not** uninstall to reconfigure: that drops this plugin's + (repeatable per key); against an already-installed plugin it prints `already installed` + **and still writes the value**. Do **not** uninstall to reconfigure: that drops this plugin's entire stored `pluginConfigs` entry, resetting every option in the README's Options reference - to its manifest default. Run either route from the project the plugin is installed in. For the - rerun, always pass `-s` with the scope `claude plugin list` reports for this plugin; from the - home directory pass `user`. Read each route's output, not only its exit code, to tell a saved - value from a rejected one. - - **Pointer**: for how each route resolves the install, its scope default, what it prints - against an installed plugin, and what it prints and exits with on a rejected value, fetch - [Plugin commands reference: plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) - and [plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) - live. - - **As of**: 2026-11-03 - - **Recheck trigger**: either section changes how it finds an install, its scope default, or - its output or exit code on an installed plugin or a rejected value. - - This skill never writes user settings or `pluginConfigs`. Afterwards rerun `check` in a - **fresh session** and report the observed effective value, never an unobserved change. - - **Pointer**: for when a saved value reaches skill content and hooks, fetch - [Plugin manifest reference: Reference a saved value](https://code.claude.com/docs/en/plugins-reference#reference-a-saved-value) - and [plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) - live. - - **As of**: 2026-11-03 - - **Recheck trigger**: either section changes when a saved value takes effect. + to its manifest default. The value lands in user settings whichever route writes it. + `claude plugin configure` has no scope flag, so run it from the project the plugin is installed + in. For the rerun, `-s` defaults to `user`; pass the scope `claude plugin list` reports for this + plugin, and for a `project` or `local` scope run from that project's directory, so the rerun + matches the existing install record; from the home directory pass `user`. A rerun at another + scope adds an install record at that scope and enables the plugin there. Check each route's own failure signal: + `--values-stdin` rejects a bad value with exit 1 and saves nothing, but stores an empty string + as `""`; the `--config` rerun prints a warning for a rejected value yet exits 0, so read its + output. This skill never writes user settings or `pluginConfigs`. + Afterwards rerun `check` in a **fresh session**. The rendered + `${user_config.*}` is injected at skill load and each hook receives its + `CLAUDE_PLUGIN_OPTION_*` from an environment fixed at session start, so a same-session + `check` still reports the OLD value; report the observed effective value, never an + unobserved change. After pointing at a remediation, re-run the relevant `check` probe live via Bash (a pre-computed row predates the remediation, so never re-read it) and report its actual result. Never claim resolved on diff --git a/plugins/kindle-dedrm/skills/manage/SKILL.md b/plugins/kindle-dedrm/skills/manage/SKILL.md index 0e73eb3dec6..a73339cd2d4 100644 --- a/plugins/kindle-dedrm/skills/manage/SKILL.md +++ b/plugins/kindle-dedrm/skills/manage/SKILL.md @@ -72,7 +72,7 @@ Sequence: 6. **Re-run keyfinder** (`~/Tools/Kindle_Key_Finder/Run_keyfinder_admin.vbs`). Saved config auto-loads; tool processes only new books. 7. **Verify new EPUBs** under Calibre Library. -If user reports a cached installer popped up during step 3, delete it via step 4 immediately and verify Kindle.exe still reports 2.8.0.70980. +If user reports a cached installer popped up during step 3, that's expected. Amazon staged 2.9.x. Delete it via step 4 immediately and verify Kindle.exe still reports 2.8.0.70980. ## Action: update @@ -172,7 +172,7 @@ The skill should NEVER offer to delete the user's Calibre Library. Those are the | techy-notes.com tutorial 404s or moves | Pivot to epubor.com tutorial (secondary); update `reference/sources.md` | | Kindle for PC ships a version > 2.9.1 not in `KFXARCHIVER_TOOL_MAP` | Wait for KFXArchiver update; document in `reference/troubleshooting.md` | | Calibre's KFX Input plugin renamed in catalog | Update plugin name reference in `reference/workflow.md` | -| User reports a sync that left a cached installer past firewall re-enable | Tighten timing in `scripts/sync-prep.sh`. Possibly add an automatic `sync-finalize.sh` invocation when Kindle.exe quits | +| User reports a sync that left a 2.9.x cached installer past firewall re-enable | Tighten timing in `scripts/sync-prep.sh`. Possibly add an automatic `sync-finalize.sh` invocation when Kindle.exe quits | ## Spoke paths diff --git a/plugins/machine-health/skills/setup/SKILL.md b/plugins/machine-health/skills/setup/SKILL.md index 06e625ffcdc..adaac8d245b 100644 --- a/plugins/machine-health/skills/setup/SKILL.md +++ b/plugins/machine-health/skills/setup/SKILL.md @@ -268,29 +268,26 @@ Reject an argument targeting an unknown check id, remediation or muted key with Headless fallback, for a Claude Code release without `plugin configure`: rerun `claude plugin install machine-health@ -s --config report_dir=` - (repeatable per key). Do **not** uninstall to reconfigure: that drops the plugin's entire + (repeatable per key). Against an already-installed plugin it prints `already installed` and + still writes the value. Do **not** uninstall to reconfigure: that drops the plugin's entire stored `pluginConfigs` entry, resetting every option in the README's Options reference to its manifest default. Run either route from the project the plugin is installed in. For the rerun, always pass `-s` with the scope `claude plugin list` reports; from the home directory pass `user`. Read each route's output, not only its exit code, to tell a saved value from a rejected one. - - **Pointer**: for how each route resolves the install, its scope default, what it prints - against an installed plugin, and what it prints and exits with on a rejected value, fetch + - **Pointer**: for how each route resolves the install, its scope default, and what it prints + and exits with on a rejected value, fetch [Plugin commands reference: plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) and [plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) live. - **As of**: 2026-11-03 - **Recheck trigger**: either section changes how it finds an install, its scope default, or - its output or exit code on an installed plugin or a rejected value. + its output or exit code on a rejected value. - This skill never writes user settings or `pluginConfigs`. Afterwards rerun `check` in a - **fresh session** and report the observed effective value, never an unobserved change. - - **Pointer**: for when a saved value reaches skill content and hooks, fetch - [Plugin manifest reference: Reference a saved value](https://code.claude.com/docs/en/plugins-reference#reference-a-saved-value) - and [plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) - live. - - **As of**: 2026-11-03 - - **Recheck trigger**: either section changes when a saved value takes effect. + This skill never writes user settings or `pluginConfigs`. Afterwards rerun + `check` in a **fresh session**. The rendered `${user_config.*}` and each hook's + `CLAUDE_PLUGIN_OPTION_*` are fixed at session start, so a same-session `check` still reports + the OLD value; report the observed effective value, never an unobserved change. Re-running `apply` after everything is already set changes nothing and reports "already configured". From b1839e8d3157230e37540c2d6dc8a3188d899228 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 3 Nov 2026 19:30:39 -0500 Subject: [PATCH 5/7] docs(playbooks): exempt required pointer swaps from the cut eval rule The skill criteria now say that replacing a restated upstream fact with a pointer to its live upstream section, as the upstream-pointer rule requires, needs no eval run, while a removed sentence that gives a reason the skill acts on still needs eval evidence of no loss, or it stays. The review summary of the criteria names the exemption. Restore the reason sentences the pointer swaps removed from the architecture, context7, improvement, kindle-dedrm, machine-health and review skills, dropping only a vendor installer version and the editor the PATH ceiling comes from, and correct those plugins' fragments. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015te8Cr8u7uFJG4tdeUACLz --- ...7-restated-upstream-facts-pointers-3acb239e.md | 9 ++++----- ...7-restated-upstream-facts-pointers-6a9194f5.md | 4 ++-- ...7-restated-upstream-facts-pointers-6d183912.md | 9 +++++---- ...7-restated-upstream-facts-pointers-2f3b9d60.md | 6 ++---- ...7-restated-upstream-facts-pointers-52f16bb4.md | 13 ++++++------- ...7-restated-upstream-facts-pointers-7d4e2b19.md | 9 +++++++++ ...7-restated-upstream-facts-pointers-1f29181d.md | 7 +++---- docs/review/skills-and-agents.md | 2 +- .../architecture/skills/map-containers/SKILL.md | 2 +- plugins/architecture/skills/map-context/SKILL.md | 2 +- .../architecture/skills/map-landscape/SKILL.md | 4 ++-- plugins/context7/skills/lookup/SKILL.md | 2 +- .../improvement/skills/find/context/ci-health.md | 15 ++++++++------- plugins/kindle-dedrm/skills/manage/SKILL.md | 8 ++++---- .../audit/reference/windows/check-catalog.md | 2 +- plugins/machine-health/skills/setup/SKILL.md | 12 ++++++++---- .../skill-authoring/reference/skill-criteria.md | 11 +++++++---- plugins/review/skills/quality-gate/context/pr.md | 15 ++++++++++----- 18 files changed, 75 insertions(+), 57 deletions(-) create mode 100644 .changes/playbooks/docs-12697-restated-upstream-facts-pointers-7d4e2b19.md diff --git a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md index be20d61b4ca..92c59508dc9 100644 --- a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md +++ b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md @@ -4,11 +4,10 @@ bump: patch ### Changed -- `map-containers` and `map-context` no longer give mermaid's C4 status as the reason the - dialect key refuses mermaid; the refusal, the unset key and the no-diagram fallback stay, with a +- `map-containers` and `map-context` keep the reason the dialect key refuses mermaid and add a pointer to the Mermaid C4 page. -- `map-landscape` no longer states what each dialect offers for a landscape view. It keeps that - the mermaid output is a `C4Context` diagram without a focal system and points at the - Structurizr `systemLandscape` view and the Mermaid C4 page. +- `map-landscape` no longer states Structurizr's landscape view type. It keeps why the mermaid + output is a `C4Context` diagram without a focal system and points at the Structurizr + `systemLandscape` view and the Mermaid C4 page. - `reference/config.md` no longer calls mermaid C4 experimental or restates the recheck trigger; it points at the authoring-formats convention's record. diff --git a/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md b/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md index 842ee9fa738..651a65eaee7 100644 --- a/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md +++ b/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md @@ -6,5 +6,5 @@ bump: patch - `lookup` and its MCP reference no longer list the MCP tools' parameters or describe them; they keep the tool-list check and the tool-to-CLI mapping and point at Context7's MCP Tools section. -- The Windows Git Bash gotcha keeps the `MSYS_NO_PATHCONV=1` prefix rule and points at MSYS2's - automatic path conversion section instead of describing the rewrite. +- The Windows Git Bash gotcha keeps the rewrite it guards against and the `MSYS_NO_PATHCONV=1` + prefix rule, and points at MSYS2's automatic path conversion section. diff --git a/.changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md b/.changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md index 97499cb406e..d8301e5ebb8 100644 --- a/.changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md +++ b/.changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md @@ -4,7 +4,8 @@ bump: patch ### Changed -- The `find` CI-health context no longer states the REST `per_page` cap, what `run_attempt`, - `run_started_at` and `created_at` mean, or which filters and options the GitHub MCP tools lack. - It keeps the window and paging rules, the three fields per run and the MCP-path rule, and - points at the workflow-runs REST sections and the GitHub MCP Server tools list. +- The `find` CI-health context no longer states the REST `per_page` cap, what `run_attempt` and + the latest attempt's duration record, or the `get_job_logs` failed-jobs option. It keeps the + window and paging rules with their reasons, the three fields per run, why `created_at` is not + used, and why the MCP path cannot window by date, and points at the workflow-runs REST sections + and the GitHub MCP Server tools list. diff --git a/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md index 11651da424d..df85ce9fa7b 100644 --- a/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md +++ b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md @@ -4,7 +4,5 @@ bump: patch ### Changed -- `manage` no longer describes how Amazon stages installers or what the cached installer does. - The rules stay: never open Kindle for PC while the block is disabled except to sync with the - keyfinder ready, never run the cached installer, delete it, and follow the - `sync-finalize.sh` logic. +- `manage` no longer names the installer version Amazon stages. The hard safety rules and their + reasons stay. diff --git a/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md index 9973a490908..8f02c1bc69e 100644 --- a/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md +++ b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md @@ -4,10 +4,9 @@ bump: patch ### Changed -- `setup` no longer describes `claude plugin configure`'s install lookup, the rerun's `-s` - default, or either route's exit code and empty-string handling. It keeps passing the scope - `claude plugin list` reports and reading each route's output, and points at the - `plugin configure` and `plugin install` sections of the plugin commands reference. -- The Windows check catalog's environment and PATH health entry no longer explains the User Path - `CRIT` threshold with a claim about the System Properties editor; 2047 stays as this audit's own - threshold. +- `setup` no longer states which settings file either `plugin configure` route writes. It keeps + the scope and failure-signal guidance with their reasons, and points at the `plugin configure` + and `plugin install` sections of the plugin commands reference. +- The Windows check catalog's environment and PATH health entry no longer names the System + Properties editor as the source of the 2047 User Path `CRIT` threshold; it keeps that further + appends are silently discarded. diff --git a/.changes/playbooks/docs-12697-restated-upstream-facts-pointers-7d4e2b19.md b/.changes/playbooks/docs-12697-restated-upstream-facts-pointers-7d4e2b19.md new file mode 100644 index 00000000000..7e888657aa2 --- /dev/null +++ b/.changes/playbooks/docs-12697-restated-upstream-facts-pointers-7d4e2b19.md @@ -0,0 +1,9 @@ +--- +bump: patch +--- + +### Changed + +- `skill-authoring`'s skill criteria exempt replacing a restated upstream fact with a pointer to + its live upstream section from the cut eval rule. A removed sentence that gives a reason the + skill acts on still needs eval evidence of no loss, or it stays. diff --git a/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md b/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md index 7e214b0a5cd..48ca7915969 100644 --- a/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md +++ b/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md @@ -4,9 +4,8 @@ bump: patch ### Changed -- The `quality-gate` PR mode no longer describes how the `code-review` marketplace plugin runs - or what it and the managed service post. It keeps the gate by effect and when this mode uses - each surface, and points at the plugin's Commands section and the local review's reads-and-edits - section. +- The `quality-gate` PR mode keeps why the `code-review` marketplace plugin and the managed + service are gated and adds pointers to the plugin's Commands section and the local review's + reads-and-edits section. - The `security-review` bundled-command record no longer lists what gates the native command; it keeps that the lane never depends on it and points at the commands reference. diff --git a/docs/review/skills-and-agents.md b/docs/review/skills-and-agents.md index 6be00bbefe1..1d0ce987620 100644 --- a/docs/review/skills-and-agents.md +++ b/docs/review/skills-and-agents.md @@ -4,7 +4,7 @@ version), even with a stamp; they point at the exact section, and the pointer carries an as-of date and recheck trigger: [rule](../../.claude/rules/skill-bodies-state-current-rules.md). - Skill and agent text meets the skill standard, and a cut to an existing skill ships only with - eval evidence of no loss: + eval evidence of no loss, except a restated upstream fact swapped for a pointer: [skill criteria](../../plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md). - A generic skill names no `gh` command or GitHub grammar unless it sits behind the operation's owner or in a declared-provider surface: diff --git a/plugins/architecture/skills/map-containers/SKILL.md b/plugins/architecture/skills/map-containers/SKILL.md index 58519adc737..32989c927b2 100644 --- a/plugins/architecture/skills/map-containers/SKILL.md +++ b/plugins/architecture/skills/map-containers/SKILL.md @@ -295,7 +295,7 @@ hand-written; the publish destination comes from the `medium` cascade key. Proce earlier stage takes that stage's image. - **The dialect key is `diagram_dialect.system`, and it has no default.** Every C4 view of the code reads the key the authoring-formats convention assigns to C4 system views, the same key `/planning:design` reads for its design container view. It refuses - mermaid. Unset, `containers.md` carries the tables and no diagram, + mermaid because mermaid C4 is experimental. Unset, `containers.md` carries the tables and no diagram, and the report says no view was emitted. The key is documented in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. - **Pointer**: for what mermaid's C4 support covers, see diff --git a/plugins/architecture/skills/map-context/SKILL.md b/plugins/architecture/skills/map-context/SKILL.md index 281171d7b8c..7c4e482a378 100644 --- a/plugins/architecture/skills/map-context/SKILL.md +++ b/plugins/architecture/skills/map-context/SKILL.md @@ -225,7 +225,7 @@ hand-written; the publish destination comes from the `medium` cascade key. Proce operator-stated `--actors` file. A non-interactive run passes no file, and the artifact says so. - **The dialect key is `diagram_dialect.system`, and it has no default.** Every C4 view of the code reads the key the authoring-formats convention assigns to - C4 system views, which refuses mermaid. An unset key is the + C4 system views, which refuses mermaid because mermaid C4 is experimental. An unset key is the common case: the run still writes `context.json` and a `context.md` with no diagram, and the report says no view was emitted. The key is documented in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. diff --git a/plugins/architecture/skills/map-landscape/SKILL.md b/plugins/architecture/skills/map-landscape/SKILL.md index 072c378a919..01afe807bdb 100644 --- a/plugins/architecture/skills/map-landscape/SKILL.md +++ b/plugins/architecture/skills/map-landscape/SKILL.md @@ -235,8 +235,8 @@ hand-written; the publish destination comes from the `medium` cascade key. Proce ## Gotchas -- **The two dialects are not symmetric, and mermaid is the loose one.** The mermaid output is a - `C4Context` diagram used without a focal system. +- **The two dialects are not symmetric, and mermaid is the loose one.** Mermaid has no landscape diagram type, so the mermaid output + is a `C4Context` diagram used without a focal system. - **Pointer**: for the landscape view each dialect offers, see [Structurizr DSL: systemLandscape view](https://docs.structurizr.com/dsl/language#systemlandscape-view) and [Mermaid: C4 Diagrams](https://mermaid.js.org/syntax/c4.html#c4-diagrams). diff --git a/plugins/context7/skills/lookup/SKILL.md b/plugins/context7/skills/lookup/SKILL.md index 439d85a050d..caf32c8f0db 100644 --- a/plugins/context7/skills/lookup/SKILL.md +++ b/plugins/context7/skills/lookup/SKILL.md @@ -79,7 +79,7 @@ never hand a `${…}` token from those files to the Bash tool. ## Gotchas -- **Windows Git Bash**: always prefix `ctx7 docs`, and `ctx7 search --library /org/project`, with `MSYS_NO_PATHCONV=1`; `ctx7 library` is unaffected. Detail: [context/cli.md](context/cli.md). +- **Windows Git Bash** rewrites `ctx7 docs /org/project` into `C:/Program Files/Git/org/project`. Always prefix `ctx7 docs`, and `ctx7 search --library /org/project`, with `MSYS_NO_PATHCONV=1`; `ctx7 library` is unaffected. Detail: [context/cli.md](context/cli.md). - **Pointer**: for how an MSYS2-based shell rewrites a `/org/project` argument, see [MSYS2: Automatic Unix ⟶ Windows Path Conversion](https://www.msys2.org/docs/filesystem-paths/#automatic-unix-windows-path-conversion). - **As of**: 2026-11-03 diff --git a/plugins/improvement/skills/find/context/ci-health.md b/plugins/improvement/skills/find/context/ci-health.md index d75b8a5cdff..2ef4df79635 100644 --- a/plugins/improvement/skills/find/context/ci-health.md +++ b/plugins/improvement/skills/find/context/ci-health.md @@ -64,8 +64,8 @@ parameters it applies to. Use the documented `created` date filter: - Write the window bounds as **literal ISO dates** you compute yourself. Do not shell out to date arithmetic, whose flags are dialect-split. - If a window's `total_count` exceeds one page, either narrow the window or fetch the few extra - pages *within* that window. Shallow pages inside a bounded window are fine; never walk pages - across the whole history. + pages *within* that window. Shallow pages inside a bounded window are fine; an unbounded page + walk across the whole history is what the cap breaks. - **Pointer**: for the page-size limit, read the `per_page` parameter in [List workflow runs for a repository](https://docs.github.com/en/rest/actions/workflow-runs#list-workflow-runs-for-a-repository). - **As of**: 2026-11-03 @@ -75,7 +75,7 @@ parameters it applies to. Use the documented `created` date filter: Per completed run, three fields do all the work: `conclusion` (failure ratio), `run_attempt` (retry detection: `run_attempt > 1`), and `updated_at − run_started_at` (wall duration; use -`run_started_at`, not `created_at`). +`run_started_at`, not `created_at`, which includes queue time). - **Pointer**: for what each field records, read the response schema of [Get a workflow run](https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run). @@ -103,12 +103,13 @@ gh api "repos/$OWNER/$REPO/actions/runs?created=2026-07-01..2026-07-07&per_page= | @tsv' ``` -Via the GitHub MCP tools, read the same per-run fields (`conclusion`, `run_attempt`, -`run_started_at`, `updated_at`), but do not window by date. On the MCP path, read the most -recent page(s) only, cite the covered span verbatim ("last N runs, +Via the GitHub MCP tools, the per-run fields are the same (`conclusion`, `run_attempt`, +`run_started_at`, `updated_at`) but the window mechanics are NOT: the `actions_list` tooling +exposes no `created` date filter, so date-windowed iteration is unreachable through it. On the +MCP path, read the most recent page(s) only, cite the covered span verbatim ("last N runs, <oldest>..<newest>"), and record the uncovered windows as a `gap:` line. Never page deep to reach them and never present a recent-page sample as full-window coverage. Full date-window -iteration uses the REST call above (`gh api` or an equivalent raw-request path). Use +iteration needs the REST call above (`gh api` or an equivalent raw-request path). Use `get_job_logs` when a candidate needs "why is CI red" specifics. - **Pointer**: for the filters `actions_list` takes and the options `get_job_logs` offers, fetch diff --git a/plugins/kindle-dedrm/skills/manage/SKILL.md b/plugins/kindle-dedrm/skills/manage/SKILL.md index a73339cd2d4..572f5332a7f 100644 --- a/plugins/kindle-dedrm/skills/manage/SKILL.md +++ b/plugins/kindle-dedrm/skills/manage/SKILL.md @@ -38,11 +38,11 @@ Smart auto-detect when action is empty: read pre-computed context, classify stat Apply across every action. Violating any risks losing the working 2.8.0 setup or stranding the user with an upgraded Kindle that can't be downgraded without re-extracting from a different machine. -- **Never open Kindle for PC while the firewall block is disabled UNLESS the user is actively syncing new books AND has the keyfinder ready to run immediately afterward.** -- **Never run the cached installer at `%LOCALAPPDATA%\Amazon\Kindle\updates\KindleForPC-installer.exe`.** Delete it whenever it appears. +- **Never open Kindle for PC while the firewall block is disabled UNLESS the user is actively syncing new books AND has the keyfinder ready to run immediately afterward.** Amazon stages installers aggressively; one open window with internet access is enough to cache an installer that auto-runs on next launch. +- **Never run the cached installer at `%LOCALAPPDATA%\Amazon\Kindle\updates\KindleForPC-installer.exe`.** This is the auto-update payload that breaks key extraction. Delete it whenever it appears. - **Never recommend `--no-confirm` flags or batch-confirm cleanup.** Each reversal is independent; some harder to redo than others (re-pinning Kindle 2.8.0 is easy; re-syncing 50 books isn't). This holds when the user asks for "yes to all": never write, run or hand over a script or command that pipes `yes`, skips the prompts or loops over the reversals without asking. - **Never send any of these scripts, keys, or extracted files outside the user's machine.** Personal-use scope only. -- **An installer that appears is deleted at once:** if user reports "an installer popped up when I opened Kindle," immediately follow scripts/sync-finalize.sh delete logic. Do not let the installer complete. +- **The cached installer + firewall race is real:** if user reports "an installer popped up when I opened Kindle," immediately follow scripts/sync-finalize.sh delete logic. Do not let the installer complete. ## Action: setup @@ -67,7 +67,7 @@ Sequence: 1. Verify state via status.sh. Abort if firewall rule absent or ICACLS deny missing (run `setup` first). 2. **Disable firewall block** (`scripts/firewall.ps1 disable`). 3. **User opens Kindle for PC, syncs, double-clicks new books, quits Kindle.** Agent cannot drive GUI; pause for user confirmation. -4. **Delete any newly-staged installer** at `%LOCALAPPDATA%\Amazon\Kindle\updates\*` (`scripts/sync-finalize.sh`). +4. **Delete any newly-staged installer** at `%LOCALAPPDATA%\Amazon\Kindle\updates\*` (`scripts/sync-finalize.sh`). ICACLS deny prevents *future* writes but doesn't stop one that lands during the brief firewall-disabled window. 5. **Re-enable firewall block** (`scripts/firewall.ps1 enable`). 6. **Re-run keyfinder** (`~/Tools/Kindle_Key_Finder/Run_keyfinder_admin.vbs`). Saved config auto-loads; tool processes only new books. 7. **Verify new EPUBs** under Calibre Library. diff --git a/plugins/machine-health/skills/audit/reference/windows/check-catalog.md b/plugins/machine-health/skills/audit/reference/windows/check-catalog.md index 1ea08a13d20..e8c644fe6eb 100644 --- a/plugins/machine-health/skills/audit/reference/windows/check-catalog.md +++ b/plugins/machine-health/skills/audit/reference/windows/check-catalog.md @@ -744,7 +744,7 @@ All checks emit the schema in `reference/shared/output-schema.md`, and dot-sourc ``` - **Severity rubric:** - - `CRIT`: User Path length ≥ 2047, this audit's own threshold. + - `CRIT`: User Path length ≥ 2047 (further appends are silently discarded). - `WARN` when any of these hold: User Path length ≥ 1800; User Path value kind is `REG_SZ` (`String`) rather than `REG_EXPAND_SZ` (`ExpandString`); `DISABLE_AUTOUPDATER` set to a truthy diff --git a/plugins/machine-health/skills/setup/SKILL.md b/plugins/machine-health/skills/setup/SKILL.md index adaac8d245b..1e8d78edd51 100644 --- a/plugins/machine-health/skills/setup/SKILL.md +++ b/plugins/machine-health/skills/setup/SKILL.md @@ -271,10 +271,14 @@ Reject an argument targeting an unknown check id, remediation or muted key with (repeatable per key). Against an already-installed plugin it prints `already installed` and still writes the value. Do **not** uninstall to reconfigure: that drops the plugin's entire stored `pluginConfigs` entry, resetting every option in the README's Options reference to its - manifest default. Run either route from the project the plugin is installed in. For the rerun, - always pass `-s` with the scope `claude plugin list` reports; from the home directory pass - `user`. Read each route's output, not only its exit code, to tell a saved value from a - rejected one. + manifest default. `claude plugin configure` + has no scope flag and finds only an install visible from the working directory. For the rerun, + `-s` defaults to `user`; pass the scope `claude plugin list` reports, and run from that + project's directory for a `project`/`local` scope, or the rerun adds a second install record at + the scope passed and enables the plugin there; from the home directory pass `user`. Check each + route's own failure signal: `claude plugin configure` rejects a bad value with exit 1 and saves + nothing, but stores an empty string as `""`; the rerun prints a warning for a rejected value yet + exits 0, so read its output. - **Pointer**: for how each route resolves the install, its scope default, and what it prints and exits with on a rejected value, fetch [Plugin commands reference: plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) diff --git a/plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md b/plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md index 905d0badee2..d149fca127c 100644 --- a/plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md +++ b/plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md @@ -24,8 +24,8 @@ button is pressed, or preloading a font in React with `ReactDOM`. The deletion test proposes; the evals decide. Whether a model needs a line cannot be read off the text: a rule's stated reason can carry behavior, and a plausible explanation for a regression can be wrong. Unsure whether a line matters? Run the skill with the line and without it, and compare -the two versions with `/evals:plugin-eval`. A cut to an existing skill ships only when its evals show no loss -([Measurement](#measurement)). +the two versions with `/evals:plugin-eval`. A cut to an existing skill ships only when its evals show no loss, +except the pointer swap that **Cutting text** exempts ([Measurement](#measurement)). ## Frontmatter @@ -281,8 +281,11 @@ precedence rule at the top of this page). Cut text from a shipped skill by this (by hand or with `/docs-hygiene:compress`), label what it changed with `/docs-hygiene:compress compare`, then run the skill's cases with the removed text and without it (`/evals:plugin-eval --baseline --margin `). The cut ships only under step 6's -non-inferiority rule; otherwise the removed text stays. A cut to a description also re-measures -triggering on the probes (steps 3 and 4). +non-inferiority rule; otherwise the removed text stays. Replacing a restated upstream fact with a +pointer to its live upstream section, as the +[upstream-pointer rule](https://github.com/melodic-software/claude-code-plugins/blob/main/.claude/rules/skill-bodies-state-current-rules.md) +requires, needs no eval run; a removed sentence giving a reason the skill acts on still does, or it +stays. A cut to a description also re-measures triggering on the probes (steps 3 and 4). **Re-auditing shipped skills.** On each model release, re-audit every shipped skill against this page on the new model, since a line the previous model needed may now fail the deletion test. Each diff --git a/plugins/review/skills/quality-gate/context/pr.md b/plugins/review/skills/quality-gate/context/pr.md index 536de7e758f..d02a8f2b1e7 100644 --- a/plugins/review/skills/quality-gate/context/pr.md +++ b/plugins/review/skills/quality-gate/context/pr.md @@ -9,7 +9,10 @@ marketplace plugin, plus two that ship with Claude Code itself. They share a nam routinely conflated; they are distinct: - **`code-review` marketplace plugin**: `/code-review:code-review`, installed from the - `claude-plugins-official` marketplace like any other plugin. This mode never runs it as a + `claude-plugins-official` marketplace like any other plugin. A PR is its only target: it runs + parallel review agents with confidence scoring against that PR, then posts the surviving findings + back as a PR comment as its final step. It has no mode that returns them to the session instead. + This mode never runs it as a read-only pass: it is a gated surface (Mutation gate below), dispatched only on explicit opt-in. - **Pointer**: for what the plugin targets and where its findings go, see [code-review plugin: Commands](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-review#commands). @@ -44,10 +47,12 @@ the bundled-skill list. **Mutation gate.** The gate is by effect, not by flag name. It covers the plugin unconditionally, the managed service, and any bundled `/code-review` invocation whose arguments, as read live at the -pointer above, edit the working tree or post to the PR. A surface that posts to the PR or edits the -working tree violates the review modes' report-only contract. Dispatch any gated surface only on -explicit user opt-in ("post the review comment", "apply the fixes"), otherwise skip and name the -skip in the review report. +pointer above, edit the working tree or post to the PR. Every +`/code-review:code-review` run ends by posting its findings as a PR comment, and triggering the +managed service posts a full review; both violate the review modes' report-only contract, as does +any bundled invocation that posts or edits. Dispatch any gated surface only on explicit user opt-in +("post the review comment", "apply the fixes"), otherwise skip and name the skip in the review +report. - **Pointer**: for what the bundled command's run reads and edits, see [code-review: What the review reads and edits](https://code.claude.com/docs/en/code-review-local#what-the-review-reads-and-edits). From 51e77909a1e369d51647342d7eb9b06225b93726 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 3 Nov 2026 19:33:00 -0500 Subject: [PATCH 6/7] docs(architecture): drop the stale mermaid C4 experimental reason again Put map-containers and map-context back to the text issue rows r009 and r010 call for: the dialect-key gotcha no longer says mermaid C4 is experimental, since the Mermaid C4 page does not. The changelog fragment says the claim is dropped. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015te8Cr8u7uFJG4tdeUACLz --- .../docs-12697-restated-upstream-facts-pointers-3acb239e.md | 4 ++-- plugins/architecture/skills/map-containers/SKILL.md | 2 +- plugins/architecture/skills/map-context/SKILL.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md index 92c59508dc9..677599e57d2 100644 --- a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md +++ b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md @@ -4,8 +4,8 @@ bump: patch ### Changed -- `map-containers` and `map-context` keep the reason the dialect key refuses mermaid and add a - pointer to the Mermaid C4 page. +- `map-containers` and `map-context` drop the claim that mermaid C4 is experimental and point at + the Mermaid C4 page. - `map-landscape` no longer states Structurizr's landscape view type. It keeps why the mermaid output is a `C4Context` diagram without a focal system and points at the Structurizr `systemLandscape` view and the Mermaid C4 page. diff --git a/plugins/architecture/skills/map-containers/SKILL.md b/plugins/architecture/skills/map-containers/SKILL.md index 32989c927b2..58519adc737 100644 --- a/plugins/architecture/skills/map-containers/SKILL.md +++ b/plugins/architecture/skills/map-containers/SKILL.md @@ -295,7 +295,7 @@ hand-written; the publish destination comes from the `medium` cascade key. Proce earlier stage takes that stage's image. - **The dialect key is `diagram_dialect.system`, and it has no default.** Every C4 view of the code reads the key the authoring-formats convention assigns to C4 system views, the same key `/planning:design` reads for its design container view. It refuses - mermaid because mermaid C4 is experimental. Unset, `containers.md` carries the tables and no diagram, + mermaid. Unset, `containers.md` carries the tables and no diagram, and the report says no view was emitted. The key is documented in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. - **Pointer**: for what mermaid's C4 support covers, see diff --git a/plugins/architecture/skills/map-context/SKILL.md b/plugins/architecture/skills/map-context/SKILL.md index 7c4e482a378..281171d7b8c 100644 --- a/plugins/architecture/skills/map-context/SKILL.md +++ b/plugins/architecture/skills/map-context/SKILL.md @@ -225,7 +225,7 @@ hand-written; the publish destination comes from the `medium` cascade key. Proce operator-stated `--actors` file. A non-interactive run passes no file, and the artifact says so. - **The dialect key is `diagram_dialect.system`, and it has no default.** Every C4 view of the code reads the key the authoring-formats convention assigns to - C4 system views, which refuses mermaid because mermaid C4 is experimental. An unset key is the + C4 system views, which refuses mermaid. An unset key is the common case: the run still writes `context.json` and a `context.md` with no diagram, and the report says no view was emitted. The key is documented in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. From 375700a64dc906cf45a616cc2394506955a423b4 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 3 Nov 2026 19:42:10 -0500 Subject: [PATCH 7/7] docs: drop the restored code-review posting claims and finish the C4 swap Put the quality-gate PR mode back to its pointer version: the restored sentences said the code-review plugin only targets a PR and always posts its findings, which its README contradicts (terminal output by default, a PR comment only with --comment). Restore the context7 MCP reference's sentence on why the CLI and MCP transports are treated alike, which no pointer replaced. Drop the mermaid C4 experimental claim from map-components as map-containers and map-context already do, keeping the refusal and the no-diagram fallback and pointing at the Mermaid C4 page. Update the three plugins' fragments to match. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015te8Cr8u7uFJG4tdeUACLz --- ...7-restated-upstream-facts-pointers-3acb239e.md | 2 +- ...7-restated-upstream-facts-pointers-6a9194f5.md | 3 ++- ...7-restated-upstream-facts-pointers-1f29181d.md | 6 +++--- .../architecture/skills/map-components/SKILL.md | 15 +++++++++------ plugins/context7/skills/lookup/context/mcp.md | 2 ++ plugins/review/skills/quality-gate/context/pr.md | 15 +++++---------- 6 files changed, 22 insertions(+), 21 deletions(-) diff --git a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md index 677599e57d2..61cbd71481a 100644 --- a/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md +++ b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md @@ -4,7 +4,7 @@ bump: patch ### Changed -- `map-containers` and `map-context` drop the claim that mermaid C4 is experimental and point at +- `map-components`, `map-containers` and `map-context` drop the claim that mermaid C4 is experimental and point at the Mermaid C4 page. - `map-landscape` no longer states Structurizr's landscape view type. It keeps why the mermaid output is a `C4Context` diagram without a focal system and points at the Structurizr diff --git a/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md b/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md index 651a65eaee7..10efe6f010c 100644 --- a/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md +++ b/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md @@ -5,6 +5,7 @@ bump: patch ### Changed - `lookup` and its MCP reference no longer list the MCP tools' parameters or describe them; they - keep the tool-list check and the tool-to-CLI mapping and point at Context7's MCP Tools section. + keep the tool-list check, the tool-to-CLI mapping and why the two transports are treated alike, + and point at Context7's MCP Tools section. - The Windows Git Bash gotcha keeps the rewrite it guards against and the `MSYS_NO_PATHCONV=1` prefix rule, and points at MSYS2's automatic path conversion section. diff --git a/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md b/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md index 48ca7915969..555e9d33bd7 100644 --- a/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md +++ b/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md @@ -4,8 +4,8 @@ bump: patch ### Changed -- The `quality-gate` PR mode keeps why the `code-review` marketplace plugin and the managed - service are gated and adds pointers to the plugin's Commands section and the local review's - reads-and-edits section. +- The `quality-gate` PR mode no longer states what the `code-review` marketplace plugin targets + or where its findings go; it keeps the plugin gated and points at the plugin's Commands section + and the local review's reads-and-edits section. - The `security-review` bundled-command record no longer lists what gates the native command; it keeps that the lane never depends on it and points at the commands reference. diff --git a/plugins/architecture/skills/map-components/SKILL.md b/plugins/architecture/skills/map-components/SKILL.md index 466a2aa9067..0a3de5c523d 100644 --- a/plugins/architecture/skills/map-components/SKILL.md +++ b/plugins/architecture/skills/map-components/SKILL.md @@ -231,12 +231,15 @@ Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ ## Gotchas -- **The dialect key is `diagram_dialect.system`, and it has no default.** The - Every C4 view of the code reads the key the - authoring-formats convention assigns to C4 system views, which refuses - mermaid because mermaid C4 is experimental. The key is documented in - `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. Unset, `components.md` carries the - tables and no diagram, and the report says no view was emitted. +- **The dialect key is `diagram_dialect.system`, and it has no default.** Every C4 + view of the code reads the key the authoring-formats convention assigns to C4 system views, + which refuses mermaid. The key is documented in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. + Unset, `components.md` carries the tables and no diagram, and the report says no view was + emitted. + - **Pointer**: for what mermaid's C4 support covers, see + [Mermaid: C4 Diagrams](https://mermaid.js.org/syntax/c4.html#c4-diagrams). + - **As of**: 2026-11-03 + - **Recheck trigger**: that page changes the status of C4 support or adds a diagram type. - **A component diagram is one container.** Claim: the C4 component diagram scopes to a single container, and its primary elements are the components inside that container. The model is notation-independent. Basis: diff --git a/plugins/context7/skills/lookup/context/mcp.md b/plugins/context7/skills/lookup/context/mcp.md index 8c616d9a960..07ecefc8c30 100644 --- a/plugins/context7/skills/lookup/context/mcp.md +++ b/plugins/context7/skills/lookup/context/mcp.md @@ -56,6 +56,8 @@ or its as-of date changes): | `mcp__context7__resolve-library-id` | `ctx7 library ` | | `mcp__context7__query-docs` | `MSYS_NO_PATHCONV=1 ctx7 docs ` | +Same input shape as CLI, same backend, and same output substance. Only the transport differs. + - **Pointer**: for what each tool does and the arguments it takes, fetch [Context7: MCP Tools](https://github.com/upstash/context7#mcp-tools) live. - **As of**: 2026-11-03 diff --git a/plugins/review/skills/quality-gate/context/pr.md b/plugins/review/skills/quality-gate/context/pr.md index d02a8f2b1e7..536de7e758f 100644 --- a/plugins/review/skills/quality-gate/context/pr.md +++ b/plugins/review/skills/quality-gate/context/pr.md @@ -9,10 +9,7 @@ marketplace plugin, plus two that ship with Claude Code itself. They share a nam routinely conflated; they are distinct: - **`code-review` marketplace plugin**: `/code-review:code-review`, installed from the - `claude-plugins-official` marketplace like any other plugin. A PR is its only target: it runs - parallel review agents with confidence scoring against that PR, then posts the surviving findings - back as a PR comment as its final step. It has no mode that returns them to the session instead. - This mode never runs it as a + `claude-plugins-official` marketplace like any other plugin. This mode never runs it as a read-only pass: it is a gated surface (Mutation gate below), dispatched only on explicit opt-in. - **Pointer**: for what the plugin targets and where its findings go, see [code-review plugin: Commands](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-review#commands). @@ -47,12 +44,10 @@ the bundled-skill list. **Mutation gate.** The gate is by effect, not by flag name. It covers the plugin unconditionally, the managed service, and any bundled `/code-review` invocation whose arguments, as read live at the -pointer above, edit the working tree or post to the PR. Every -`/code-review:code-review` run ends by posting its findings as a PR comment, and triggering the -managed service posts a full review; both violate the review modes' report-only contract, as does -any bundled invocation that posts or edits. Dispatch any gated surface only on explicit user opt-in -("post the review comment", "apply the fixes"), otherwise skip and name the skip in the review -report. +pointer above, edit the working tree or post to the PR. A surface that posts to the PR or edits the +working tree violates the review modes' report-only contract. Dispatch any gated surface only on +explicit user opt-in ("post the review comment", "apply the fixes"), otherwise skip and name the +skip in the review report. - **Pointer**: for what the bundled command's run reads and edits, see [code-review: What the review reads and edits](https://code.claude.com/docs/en/code-review-local#what-the-review-reads-and-edits).