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..61cbd71481a --- /dev/null +++ b/.changes/architecture/docs-12697-restated-upstream-facts-pointers-3acb239e.md @@ -0,0 +1,13 @@ +--- +bump: patch +--- + +### Changed + +- `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 + `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/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..10efe6f010c --- /dev/null +++ b/.changes/context7/docs-12697-restated-upstream-facts-pointers-6a9194f5.md @@ -0,0 +1,11 @@ +--- +bump: patch +--- + +### Changed + +- `lookup` and its MCP reference no longer list the MCP tools' parameters or describe them; they + 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/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..d8301e5ebb8 --- /dev/null +++ b/.changes/improvement/docs-12697-restated-upstream-facts-pointers-6d183912.md @@ -0,0 +1,11 @@ +--- +bump: patch +--- + +### Changed + +- 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 new file mode 100644 index 00000000000..df85ce9fa7b --- /dev/null +++ b/.changes/kindle-dedrm/docs-12697-restated-upstream-facts-pointers-2f3b9d60.md @@ -0,0 +1,8 @@ +--- +bump: patch +--- + +### Changed + +- `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 new file mode 100644 index 00000000000..8f02c1bc69e --- /dev/null +++ b/.changes/machine-health/docs-12697-restated-upstream-facts-pointers-52f16bb4.md @@ -0,0 +1,12 @@ +--- +bump: patch +--- + +### Changed + +- `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/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/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 new file mode 100644 index 00000000000..555e9d33bd7 --- /dev/null +++ b/.changes/review/docs-12697-restated-upstream-facts-pointers-1f29181d.md @@ -0,0 +1,11 @@ +--- +bump: patch +--- + +### Changed + +- 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/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/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/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/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/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..01afe807bdb 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.** 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). + - **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..caf32c8f0db 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. @@ -79,6 +80,10 @@ 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). + - **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..07ecefc8c30 100644 --- a/plugins/context7/skills/lookup/context/mcp.md +++ b/plugins/context7/skills/lookup/context/mcp.md @@ -51,12 +51,17 @@ 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 ` | + +Same input shape as CLI, same backend, and same output substance. Only the transport differs. -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..2ef4df79635 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; 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 + - **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`, 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). +- **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): @@ -102,7 +110,13 @@ MCP path, read the most recent page(s) only, cite the covered span verbatim ("la <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. +`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..572f5332a7f 100644 --- a/plugins/kindle-dedrm/skills/manage/SKILL.md +++ b/plugins/kindle-dedrm/skills/manage/SKILL.md @@ -38,7 +38,7 @@ 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 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. 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..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,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 (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 @@ -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 cf8b904608d..1e8d78edd51 100644 --- a/plugins/machine-health/skills/setup/SKILL.md +++ b/plugins/machine-health/skills/setup/SKILL.md @@ -271,14 +271,24 @@ 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` + 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. This skill never writes user settings or `pluginConfigs`. Afterwards rerun + 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) + 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/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 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