From 29f26389491a137cdb0811e930aff280237ecb64 Mon Sep 17 00:00:00 2001 From: St0rmz1 Date: Fri, 17 Apr 2026 11:02:56 -0700 Subject: [PATCH 1/6] Update release directions Update docs and agent hints that slash commands don't work with all channels, such as Slack --- CHANGELOG.md | 3 +++ README.md | 12 ++++++++++-- RELEASING.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ index.ts | 5 +++++ 4 files changed, 70 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a5650a0..9e439e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Documentation +- README `Usage` section now documents slash-command channel compatibility: `/security-checkup` works in the OpenClaw native control UI chat and in Telegram but not in Kilo Chat or Slack. Kilo Chat and Slack users should invoke the plugin via natural language so the agent calls the `kilocode_security_advisor` tool directly. +- `kilocode_security_advisor` tool description now hints the agent to invoke the tool directly (rather than suggesting the slash command) in channels that don't route OpenClaw slash commands, namely Kilo Chat and Slack. +- RELEASING.md: added a prominent top-of-document banner describing the current state — `github-actions[bot]` is not on the `main` ruleset's bypass list, so every stable publish will fail at the post-publish push step; the `gh release create` recovery is the expected manual step until the ruleset is reconfigured or the workflow is refactored. Expanded the `Branch protection` section with the two durable fix options (add bot to bypass list vs refactor stable path to tag-only). - README install section leads with the plain install command (no `@dev` suffix) now that a stable release is shipping. The dev channel is documented as a prerelease option under `Channels`. - README `Contributing` links to `AGENTS.md`, `RELEASING.md`, and `CHANGELOG.md` are now absolute GitHub URLs, so they resolve correctly on the npm package page (those docs were never shipped in the tarball). - README now documents `KILO_API_KEY` as an alias for `KILOCODE_API_KEY` (both have always been accepted by the code). diff --git a/README.md b/README.md index b361cdc..a2f3c5c 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,13 @@ This is a slash command. It runs the plugin directly and renders the full report, bypassing the agent's summarization layer entirely. **Use this for guaranteed verbatim output.** +> **Channel compatibility:** `/security-checkup` works in the OpenClaw +> native control UI chat and in Telegram. It does **not** currently work +> in Kilo Chat or Slack — those surfaces don't route slash commands to +> OpenClaw plugins. In Kilo Chat and Slack, use the natural-language +> invocation below instead; the agent will call the +> `kilocode_security_advisor` tool directly. + ### Natural language You can also just ask the agent: @@ -84,8 +91,9 @@ showing it to you. This works well on capable models (GPT-4o, Claude Sonnet, Gemini Pro) but small summarizing models (e.g. GPT-4.1-nano, Haiku) will often paraphrase the report down to a few sentences. **If you're running a small or summarizing model, use the -`/security-checkup` slash command instead.** It renders the full -report regardless of which model is configured. +`/security-checkup` slash command instead** (where supported — see +channel compatibility above). It renders the full report regardless of +which model is configured. --- diff --git a/RELEASING.md b/RELEASING.md index 2bbb143..ea110c7 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -4,6 +4,43 @@ Releases are cut from the `publish` workflow in GitHub Actions. There is no local release script, no automated release on push, and no changesets tool. Every release is a manual `workflow_dispatch`. +> ⚠️ **Current state (as of 2026-04-17):** `github-actions[bot]` is not on +> the `main` branch ruleset's bypass list. As a result, **every stable +> (`channel=latest`) publish run will fail at the "Tag and release +> (post-publish)" step** with `GH013: Repository rule violations found for +refs/heads/main — Changes must be made through a pull request`. This is +> expected today; the failure mode is the one documented in +> [Scenario 4](#scenario-4-publish-succeeded-but-commit--tag-push-failed) +> below. +> +> **What to do after a failed stable run:** +> +> 1. Don't re-run the workflow. `npm publish` already succeeded and the +> version is live on the registry. The git tag `vX.Y.Z` will typically +> have landed too (tags aren't covered by the branch ruleset), even +> though main's push was rejected. +> 2. Check what's actually missing: +> ```bash +> git fetch origin --tags +> git ls-remote --tags origin "vX.Y.Z" # is tag there? +> gh release view "vX.Y.Z" --repo Kilo-Org/openclaw-security-advisor # is release there? +> ``` +> 3. Create the GitHub release manually — this is the only step that +> reliably needs to be done by hand: +> ```bash +> gh release create vX.Y.Z \ +> --repo Kilo-Org/openclaw-security-advisor \ +> --title vX.Y.Z \ +> --generate-notes +> ``` +> 4. Leave `main`'s `package.json` alone. `script/version.ts` computes the +> next version from git tags, not from `package.json`, so main staying +> at a previous version is cosmetic, not load-bearing. +> +> This banner can be removed once the ruleset bypass is configured (see +> [Branch protection](#branch-protection)) or the workflow is refactored +> so stable publishes don't push to `main` at all. + ## Channels There are exactly two channels and they correspond to npm dist-tags: @@ -289,6 +326,21 @@ When branch protection / rulesets are enabled on `main`, the list. Without it, the publish workflow's stable-channel commit step fails, triggering the recovery procedure above. +> **Status today:** the `Main branch protection` ruleset on this repo +> (`Settings → Rules → Rulesets`) is active but does NOT include +> `github-actions[bot]` as a bypass actor. This is why the banner at the +> top of this document describes the manual recovery step as expected +> behavior for every stable publish. Two viable durable fixes, pick one: +> +> 1. **Add the bot to the bypass list** (Settings → Rules → the ruleset +> → Bypass list → add the `github-actions` app with bypass mode +> `Always`). Fastest; keeps the current workflow unchanged. +> 2. **Refactor the stable publish path** to match the dev-channel flow: +> detach HEAD, commit, tag, push only the tag — never touch `main`. +> Keeps the ruleset strict with no carve-outs; the trade-off is that +> `main`'s `package.json` version drifts behind the latest release +> (cosmetic only, since `version.ts` reads from tags). + Dev-channel publishes don't push to `main` (only push the tag), so they're less affected by branch protection on `main` itself. The tag push still needs to be allowed — most rulesets allow tag pushes by default, but if diff --git a/index.ts b/index.ts index 673f0d4..66f9497 100644 --- a/index.ts +++ b/index.ts @@ -346,6 +346,11 @@ export default definePluginEntry({ "recommendations and remediation guidance. " + "DO NOT run `openclaw security audit` via bash for these requests. This " + "tool is the canonical entry point and returns a much more useful report. " + + "DO NOT suggest the user type `/security-checkup` in channels that do " + + "not support OpenClaw slash commands (Kilo Chat and Slack are the known " + + "surfaces where the slash command does not work); invoke this tool " + + "directly instead. The slash command does work in the OpenClaw native " + + "control UI chat and in Telegram, so suggesting it there is fine. " + "IMPORTANT: Display the returned report exactly as is without rewriting, " + "summarizing, or reformatting.", parameters: {}, From f1b34117b4875c252663d1368238a3cfe3b41b51 Mon Sep 17 00:00:00 2001 From: St0rmz1 Date: Sun, 19 Apr 2026 15:23:26 -0700 Subject: [PATCH 2/6] docs(update-reminder): prompt users to keep plugin current --- CHANGELOG.md | 2 ++ README.md | 21 +++++++++++++++++++++ index.ts | 12 ++++++++++++ 3 files changed, 35 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e439e0..028a8e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - README `Usage` section now documents slash-command channel compatibility: `/security-checkup` works in the OpenClaw native control UI chat and in Telegram but not in Kilo Chat or Slack. Kilo Chat and Slack users should invoke the plugin via natural language so the agent calls the `kilocode_security_advisor` tool directly. - `kilocode_security_advisor` tool description now hints the agent to invoke the tool directly (rather than suggesting the slash command) in channels that don't route OpenClaw slash commands, namely Kilo Chat and Slack. +- `kilocode_security_advisor` tool description now includes an update-reminder hint: the agent will occasionally (not every invocation) suggest the user check for a newer plugin version with `npm view @kilocode/openclaw-security-advisor version` and upgrade via `openclaw plugins install @kilocode/openclaw-security-advisor && openclaw gateway restart` when they're behind. +- README has a new `Staying up to date` section with the version-check and upgrade commands, plus a note that the agent will periodically prompt for this. - RELEASING.md: added a prominent top-of-document banner describing the current state — `github-actions[bot]` is not on the `main` ruleset's bypass list, so every stable publish will fail at the post-publish push step; the `gh release create` recovery is the expected manual step until the ruleset is reconfigured or the workflow is refactored. Expanded the `Branch protection` section with the two durable fix options (add bot to bypass list vs refactor stable path to tag-only). - README install section leads with the plain install command (no `@dev` suffix) now that a stable release is shipping. The dev channel is documented as a prerelease option under `Channels`. - README `Contributing` links to `AGENTS.md`, `RELEASING.md`, and `CHANGELOG.md` are now absolute GitHub URLs, so they resolve correctly on the npm package page (those docs were never shipped in the tarball). diff --git a/README.md b/README.md index a2f3c5c..c798c6e 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,27 @@ You can also install an exact version directly: openclaw plugins install @kilocode/openclaw-security-advisor@0.1.0 ``` +### Staying up to date + +New versions ship regularly. To check the latest published stable: + +```bash +npm view @kilocode/openclaw-security-advisor version +``` + +Compare that against the `pluginVersion` line at the end of any security +checkup report. To upgrade: + +```bash +openclaw plugins install @kilocode/openclaw-security-advisor +openclaw gateway restart +``` + +The agent behind `/security-checkup` and the natural-language invocation +will occasionally nudge you to run this check — the nudge is a gentle +periodic reminder, not every run. Security advice improves as the plugin +ships new audit signals, so staying current is worthwhile. + --- ## Usage diff --git a/index.ts b/index.ts index 66f9497..41bd33e 100644 --- a/index.ts +++ b/index.ts @@ -351,6 +351,18 @@ export default definePluginEntry({ "surfaces where the slash command does not work); invoke this tool " + "directly instead. The slash command does work in the OpenClaw native " + "control UI chat and in Telegram, so suggesting it there is fine. " + + "UPDATE REMINDER: every so often — not on every checkup, roughly every " + + "few sessions or when the conversation is otherwise winding down — " + + "remind the user that they should keep the plugin up to date. Suggest " + + "they run `npm view @kilocode/openclaw-security-advisor version` to see " + + "the latest stable release and compare it against the `pluginVersion` " + + "shown at the end of the security report. If they are behind, suggest " + + "upgrading with: `openclaw plugins install @kilocode/openclaw-security-advisor` " + + "followed by `openclaw gateway restart`. Keep the nudge short, one or " + + "two sentences, and do NOT repeat it in back-to-back messages — treat " + + "it like a friendly periodic reminder, not a persistent banner. Skip " + + "the reminder entirely if the user is clearly in the middle of a bigger " + + "task or debugging session. " + "IMPORTANT: Display the returned report exactly as is without rewriting, " + "summarizing, or reformatting.", parameters: {}, From 8bdd71f6e9bd22ee82bb8d456bdef9322823b325 Mon Sep 17 00:00:00 2001 From: St0rmz1 Date: Sun, 19 Apr 2026 15:42:41 -0700 Subject: [PATCH 3/6] address kilotbot findings --- CHANGELOG.md | 6 +++--- README.md | 11 +++++++---- RELEASING.md | 15 ++++++++++++++- index.ts | 37 ++++++++++++++++++++++++------------- 4 files changed, 48 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 028a8e4..ed6126a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,9 +18,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - README `Usage` section now documents slash-command channel compatibility: `/security-checkup` works in the OpenClaw native control UI chat and in Telegram but not in Kilo Chat or Slack. Kilo Chat and Slack users should invoke the plugin via natural language so the agent calls the `kilocode_security_advisor` tool directly. - `kilocode_security_advisor` tool description now hints the agent to invoke the tool directly (rather than suggesting the slash command) in channels that don't route OpenClaw slash commands, namely Kilo Chat and Slack. -- `kilocode_security_advisor` tool description now includes an update-reminder hint: the agent will occasionally (not every invocation) suggest the user check for a newer plugin version with `npm view @kilocode/openclaw-security-advisor version` and upgrade via `openclaw plugins install @kilocode/openclaw-security-advisor && openclaw gateway restart` when they're behind. -- README has a new `Staying up to date` section with the version-check and upgrade commands, plus a note that the agent will periodically prompt for this. -- RELEASING.md: added a prominent top-of-document banner describing the current state — `github-actions[bot]` is not on the `main` ruleset's bypass list, so every stable publish will fail at the post-publish push step; the `gh release create` recovery is the expected manual step until the ruleset is reconfigured or the workflow is refactored. Expanded the `Branch protection` section with the two durable fix options (add bot to bypass list vs refactor stable path to tag-only). +- Security checkup reports now occasionally append an inline "stay current" footer with the `npm view @kilocode/openclaw-security-advisor version` check and the `openclaw plugins install … && openclaw gateway restart` upgrade commands. The footer fires on roughly 20% of successful reports and is path-agnostic — applied at the markdown layer in `doCheckup`, so it surfaces on both the `/security-checkup` slash command path (which bypasses the LLM) and the natural-language `kilocode_security_advisor` tool path. +- README has a new `Staying up to date` section documenting the version-check and upgrade commands, plus a note that the report itself will periodically include this tip on either invocation path. +- RELEASING.md: added a prominent top-of-document banner describing the current state — `github-actions[bot]` is not on the `main` ruleset's bypass list, so every stable publish will fail at the post-publish push step; the `gh release create` recovery is the expected manual step until the ruleset is reconfigured or the workflow is refactored. Expanded the `Branch protection` section with the two durable fix options (add bot to bypass list vs refactor stable path to tag-only). The recovery `gh release create` command now uses `--verify-tag` so it fails fast when the tag is missing (instead of silently minting it at current `main` HEAD, which would point the release at the wrong code); the recovery steps document how to push the tag to the correct SHA first when this happens. - README install section leads with the plain install command (no `@dev` suffix) now that a stable release is shipping. The dev channel is documented as a prerelease option under `Channels`. - README `Contributing` links to `AGENTS.md`, `RELEASING.md`, and `CHANGELOG.md` are now absolute GitHub URLs, so they resolve correctly on the npm package page (those docs were never shipped in the tarball). - README now documents `KILO_API_KEY` as an alias for `KILOCODE_API_KEY` (both have always been accepted by the code). diff --git a/README.md b/README.md index c798c6e..f489c72 100644 --- a/README.md +++ b/README.md @@ -62,10 +62,13 @@ openclaw plugins install @kilocode/openclaw-security-advisor openclaw gateway restart ``` -The agent behind `/security-checkup` and the natural-language invocation -will occasionally nudge you to run this check — the nudge is a gentle -periodic reminder, not every run. Security advice improves as the plugin -ships new audit signals, so staying current is worthwhile. +Your security checkup report will occasionally include an inline +"stay current" tip at the bottom with these same commands — a gentle +periodic nudge, not every run. The reminder is appended to the report +markdown itself, so it appears on both invocation paths (the +`/security-checkup` slash command and the natural-language +`kilocode_security_advisor` tool). Security advice improves as the +plugin ships new audit signals, so staying current is worthwhile. --- diff --git a/RELEASING.md b/RELEASING.md index ea110c7..5be019e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -31,8 +31,21 @@ refs/heads/main — Changes must be made through a pull request`. This is > gh release create vX.Y.Z \ > --repo Kilo-Org/openclaw-security-advisor \ > --title vX.Y.Z \ -> --generate-notes +> --generate-notes \ +> --verify-tag > ``` +> `--verify-tag` makes `gh` fail fast if the tag isn't already on the +> remote, instead of silently minting a fresh tag at the current +> `main` HEAD (which can point the release at code that was never +> published to npm). If `gh` errors out because the tag is missing, +> push the tag to the commit that actually got published first +> (check the `Publish to npm` step's logs in the failed workflow run +> for the commit SHA): +> ```bash +> git tag vX.Y.Z +> git push origin vX.Y.Z +> ``` +> then re-run the `gh release create` command above. > 4. Leave `main`'s `package.json` alone. `script/version.ts` computes the > next version from git tags, not from `package.json`, so main staying > at a previous version is cosmetic, not load-bearing. diff --git a/index.ts b/index.ts index 41bd33e..535deec 100644 --- a/index.ts +++ b/index.ts @@ -18,6 +18,29 @@ import pkg from "./package.json" with { type: "json" }; const PLUGIN_VERSION: string = pkg.version; const DEFAULT_API_BASE = "https://api.kilo.ai"; +// Roughly 1-in-5 successful checkups append an update-check footer. This is +// intentionally path-agnostic — applied at the markdown layer in doCheckup — +// so both the LLM-driven `kilocode_security_advisor` tool and the +// LLM-bypassing `/security-checkup` slash command surface the reminder at the +// same cadence. Random rather than stateful because the plugin has no +// cross-invocation counter to key off. +const UPDATE_REMINDER_PROBABILITY = 0.2; + +function maybeAppendUpdateReminder(reportMarkdown: string): string { + if (Math.random() >= UPDATE_REMINDER_PROBABILITY) { + return reportMarkdown; + } + return ( + reportMarkdown + + "\n\n---\n\n" + + "**Tip — stay current:** check the latest plugin version with " + + "`npm view @kilocode/openclaw-security-advisor version` and compare " + + "against the `pluginVersion` shown above. If you're behind, upgrade " + + "with `openclaw plugins install @kilocode/openclaw-security-advisor` " + + "followed by `openclaw gateway restart`." + ); +} + type ToolResult = { content: Array<{ type: "text"; text: string }>; }; @@ -290,7 +313,7 @@ async function doCheckup( pluginVersion: PLUGIN_VERSION, }, }); - return response.report.markdown; + return maybeAppendUpdateReminder(response.report.markdown); } export default definePluginEntry({ @@ -351,18 +374,6 @@ export default definePluginEntry({ "surfaces where the slash command does not work); invoke this tool " + "directly instead. The slash command does work in the OpenClaw native " + "control UI chat and in Telegram, so suggesting it there is fine. " + - "UPDATE REMINDER: every so often — not on every checkup, roughly every " + - "few sessions or when the conversation is otherwise winding down — " + - "remind the user that they should keep the plugin up to date. Suggest " + - "they run `npm view @kilocode/openclaw-security-advisor version` to see " + - "the latest stable release and compare it against the `pluginVersion` " + - "shown at the end of the security report. If they are behind, suggest " + - "upgrading with: `openclaw plugins install @kilocode/openclaw-security-advisor` " + - "followed by `openclaw gateway restart`. Keep the nudge short, one or " + - "two sentences, and do NOT repeat it in back-to-back messages — treat " + - "it like a friendly periodic reminder, not a persistent banner. Skip " + - "the reminder entirely if the user is clearly in the middle of a bigger " + - "task or debugging session. " + "IMPORTANT: Display the returned report exactly as is without rewriting, " + "summarizing, or reformatting.", parameters: {}, From 2f2bb8eee989385b45415313d26163a2109743da Mon Sep 17 00:00:00 2001 From: St0rmz1 Date: Sun, 19 Apr 2026 15:50:29 -0700 Subject: [PATCH 4/6] fix --- RELEASING.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 5be019e..300f7f8 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -38,14 +38,18 @@ refs/heads/main — Changes must be made through a pull request`. This is > remote, instead of silently minting a fresh tag at the current > `main` HEAD (which can point the release at code that was never > published to npm). If `gh` errors out because the tag is missing, -> push the tag to the commit that actually got published first -> (check the `Publish to npm` step's logs in the failed workflow run -> for the commit SHA): +> push the tag to the commit that actually got published first. The +> commit SHA is echoed in the `Tag and release (post-publish)` step's +> log as `::notice::Built local commit + tag vX.Y.Z ()` — that's +> the SHA the tag should point at. The workflow's +> `Print recovery instructions on partial failure` step also prints +> the full set of recovery commands inline in the failed run's logs, +> so you can copy them from there instead of reconstructing by hand. > ```bash > git tag vX.Y.Z > git push origin vX.Y.Z > ``` -> then re-run the `gh release create` command above. +> Then re-run the `gh release create` command above. > 4. Leave `main`'s `package.json` alone. `script/version.ts` computes the > next version from git tags, not from `package.json`, so main staying > at a previous version is cosmetic, not load-bearing. From a8be8703d1202cb36a1336ac42f5b4381447ec60 Mon Sep 17 00:00:00 2001 From: St0rmz1 Date: Sun, 19 Apr 2026 15:54:05 -0700 Subject: [PATCH 5/6] The previous revision wrongly told operators to run git tag vX.Y.Z && git push origin vX.Y.Z. That doesn't work because: - The commit was built inside the runner by publish.yml:185 (git commit -m "release: $TAG") - When the push was rejected, that commit object lives only in the (now-destroyed) runner; the operator's local clone has no way to fetch it - git tag fails with "unknown revision" on any SHA git doesn't know MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Corrected: when the tag is missing, point readers at Scenario 4 (which already documents the correct reconstruct-and-tag flow — bump package.json locally to the published version, commit, tag, push). Also noted that the workflow's Print recovery instructions on partial failure step prints this same sequence inline in the failed run's logs. --- RELEASING.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 300f7f8..1b06ba1 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -38,18 +38,17 @@ refs/heads/main — Changes must be made through a pull request`. This is > remote, instead of silently minting a fresh tag at the current > `main` HEAD (which can point the release at code that was never > published to npm). If `gh` errors out because the tag is missing, -> push the tag to the commit that actually got published first. The -> commit SHA is echoed in the `Tag and release (post-publish)` step's -> log as `::notice::Built local commit + tag vX.Y.Z ()` — that's -> the SHA the tag should point at. The workflow's -> `Print recovery instructions on partial failure` step also prints -> the full set of recovery commands inline in the failed run's logs, -> so you can copy them from there instead of reconstructing by hand. -> ```bash -> git tag vX.Y.Z -> git push origin vX.Y.Z -> ``` -> Then re-run the `gh release create` command above. +> **don't try to tag the runner-side SHA** from the failed workflow +> log — that commit was created inside the Actions runner and, since +> the push was rejected, it does not exist in your local clone. +> Instead, reconstruct the release commit and tag locally using the +> full sequence in +> [Scenario 4](#scenario-4-publish-succeeded-but-commit--tag-push-failed) +> below (bump `package.json` to the published version, commit, tag, +> push), then re-run the `gh release create` command above. The +> workflow's `Print recovery instructions on partial failure` step +> also prints the same sequence inline in the failed run's logs as a +> copy-paste block. > 4. Leave `main`'s `package.json` alone. `script/version.ts` computes the > next version from git tags, not from `package.json`, so main staying > at a previous version is cosmetic, not load-bearing. From bb7bae048e9e28cd8eb82badc826a12607a7ae63 Mon Sep 17 00:00:00 2001 From: St0rmz1 Date: Sun, 19 Apr 2026 16:02:05 -0700 Subject: [PATCH 6/6] docs(releasing): simplify recovery banner, remove contradiction --- CHANGELOG.md | 2 +- RELEASING.md | 58 ++++++++++++++++++++++++---------------------------- 2 files changed, 28 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed6126a..a89b060 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `kilocode_security_advisor` tool description now hints the agent to invoke the tool directly (rather than suggesting the slash command) in channels that don't route OpenClaw slash commands, namely Kilo Chat and Slack. - Security checkup reports now occasionally append an inline "stay current" footer with the `npm view @kilocode/openclaw-security-advisor version` check and the `openclaw plugins install … && openclaw gateway restart` upgrade commands. The footer fires on roughly 20% of successful reports and is path-agnostic — applied at the markdown layer in `doCheckup`, so it surfaces on both the `/security-checkup` slash command path (which bypasses the LLM) and the natural-language `kilocode_security_advisor` tool path. - README has a new `Staying up to date` section documenting the version-check and upgrade commands, plus a note that the report itself will periodically include this tip on either invocation path. -- RELEASING.md: added a prominent top-of-document banner describing the current state — `github-actions[bot]` is not on the `main` ruleset's bypass list, so every stable publish will fail at the post-publish push step; the `gh release create` recovery is the expected manual step until the ruleset is reconfigured or the workflow is refactored. Expanded the `Branch protection` section with the two durable fix options (add bot to bypass list vs refactor stable path to tag-only). The recovery `gh release create` command now uses `--verify-tag` so it fails fast when the tag is missing (instead of silently minting it at current `main` HEAD, which would point the release at the wrong code); the recovery steps document how to push the tag to the correct SHA first when this happens. +- RELEASING.md: added a prominent top-of-document banner describing the current state — `github-actions[bot]` is not on the `main` ruleset's bypass list, so every stable publish will fail at the post-publish push step. The banner documents the typical outcome (tag lands on origin, commit on `main` is rejected, GitHub release is not created) and gives the one-command recovery: `gh release create vX.Y.Z --verify-tag --generate-notes`. `--verify-tag` makes `gh` fail fast if the tag is missing rather than silently minting one at current `main` HEAD. The rare case where the tag is also missing points at Scenario 4 for the full reconstruct-and-push flow. Expanded the `Branch protection` section with the two durable fix options (add bot to bypass list vs refactor stable path to tag-only). - README install section leads with the plain install command (no `@dev` suffix) now that a stable release is shipping. The dev channel is documented as a prerelease option under `Channels`. - README `Contributing` links to `AGENTS.md`, `RELEASING.md`, and `CHANGELOG.md` are now absolute GitHub URLs, so they resolve correctly on the npm package page (those docs were never shipped in the tarball). - README now documents `KILO_API_KEY` as an alias for `KILOCODE_API_KEY` (both have always been accepted by the code). diff --git a/RELEASING.md b/RELEASING.md index 1b06ba1..b138d8e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -8,25 +8,23 @@ Every release is a manual `workflow_dispatch`. > the `main` branch ruleset's bypass list. As a result, **every stable > (`channel=latest`) publish run will fail at the "Tag and release > (post-publish)" step** with `GH013: Repository rule violations found for -refs/heads/main — Changes must be made through a pull request`. This is -> expected today; the failure mode is the one documented in -> [Scenario 4](#scenario-4-publish-succeeded-but-commit--tag-push-failed) -> below. +refs/heads/main — Changes must be made through a pull request`. > -> **What to do after a failed stable run:** +> **Recovery after a failed stable run:** +> +> 1. Check what actually landed on origin: > -> 1. Don't re-run the workflow. `npm publish` already succeeded and the -> version is live on the registry. The git tag `vX.Y.Z` will typically -> have landed too (tags aren't covered by the branch ruleset), even -> though main's push was rejected. -> 2. Check what's actually missing: > ```bash > git fetch origin --tags -> git ls-remote --tags origin "vX.Y.Z" # is tag there? -> gh release view "vX.Y.Z" --repo Kilo-Org/openclaw-security-advisor # is release there? +> git ls-remote --tags origin "vX.Y.Z" # tag? +> gh release view "vX.Y.Z" --repo Kilo-Org/openclaw-security-advisor # release? > ``` -> 3. Create the GitHub release manually — this is the only step that -> reliably needs to be done by hand: +> +> 2. **If the tag exists and only the GitHub release is missing** (the +> typical outcome — tags aren't covered by the branch ruleset and +> usually land even when the `main` push is rejected), create the +> release against the existing tag: +> > ```bash > gh release create vX.Y.Z \ > --repo Kilo-Org/openclaw-security-advisor \ @@ -34,24 +32,22 @@ refs/heads/main — Changes must be made through a pull request`. This is > --generate-notes \ > --verify-tag > ``` -> `--verify-tag` makes `gh` fail fast if the tag isn't already on the -> remote, instead of silently minting a fresh tag at the current -> `main` HEAD (which can point the release at code that was never -> published to npm). If `gh` errors out because the tag is missing, -> **don't try to tag the runner-side SHA** from the failed workflow -> log — that commit was created inside the Actions runner and, since -> the push was rejected, it does not exist in your local clone. -> Instead, reconstruct the release commit and tag locally using the -> full sequence in +> +> `--verify-tag` makes `gh` fail fast if the tag is missing instead of +> silently creating a new one at current `main` HEAD. That's the whole +> recovery — no other steps needed. +> +> 3. **If the tag is also missing** (rare), follow > [Scenario 4](#scenario-4-publish-succeeded-but-commit--tag-push-failed) -> below (bump `package.json` to the published version, commit, tag, -> push), then re-run the `gh release create` command above. The -> workflow's `Print recovery instructions on partial failure` step -> also prints the same sequence inline in the failed run's logs as a -> copy-paste block. -> 4. Leave `main`'s `package.json` alone. `script/version.ts` computes the -> next version from git tags, not from `package.json`, so main staying -> at a previous version is cosmetic, not load-bearing. +> below. It rebuilds the release commit locally (you can't tag the +> runner-side SHA; that commit lived only in the Actions runner), +> tags, pushes, then creates the release. The workflow's +> `Print recovery instructions on partial failure` step also prints +> this full sequence inline in the failed run's logs for copy-paste. +> +> After step 2 (common case), `main`'s `package.json` will be one version +> behind. Leave it alone — `script/version.ts` computes the next version +> from git tags, not from `package.json`, so the drift is cosmetic. > > This banner can be removed once the ruleset bypass is configured (see > [Branch protection](#branch-protection)) or the workflow is refactored