docs: remove retired approvals from the docs - #345
Merged
Merged
Conversation
CLI v2.35.0 removed the approval commands and server #6309 removed the approval API from prod, so the hand-written pages that still describe approvals now document something users cannot do. The release automation only regenerates client_reference/ and the CLI nav, so everything here needed doing by hand. Add redirects for the five deleted client_reference pages - the update-cli-docs workflow deletes pages but never touches config/redirects.json, so those URLs were serving 404s to anyone arriving from a bookmark or a search result. Drop the approvals array from the documented custom-webhook payload, and the deployments array with it: the payload builder emits neither, and the deployments collection was dropped long ago. Repoint the kosli get trail live example at a July 2026 trail. The pinned March 2024 trail contains artifact_approval_reported events, and since the page is generated the only way to stop them reappearing on every CLI release is to pin a trail from after cyber-dojo stopped reporting approvals. Correct the built-in attestation type lists in the glossary and the controls table: approval was never an attestation type - the built-ins are generic, junit, snyk, pull_request, jira and sonar. Remove the now-dead kosli report approval live-docs modifier, and move the two tests that used it as their fixture onto commands that still exist. Docs stay slightly ahead of the server on roles: MEMBER still holds the update_approval UI action for legacy approvals, but nothing can create an approval any more, so the roles page should not advertise it.
Contributor
|
Claude finished @ToreMerkely's task in 2m 17s —— View job PR Review: Remove retired approvals from the docs
Clean, thorough removal. The changes are consistent across roles, webhook payload, tutorials, glossary, and controls. Redirects for the five deleted CLI reference pages are correct. Changelog entries follow the One thing slipped through the sweep: Improvement
This is the same issue fixed in File-by-file notes
Summary
Overall this is a well-scoped cleanup PR. The one missed file is a minor consistency issue. |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
mbevc1
approved these changes
Jul 28, 2026
dangrondahl
added a commit
that referenced
this pull request
Sep 3, 2026
Reviewed the last 20 non-bot PRs (14 touched docs) against what `doc-write` and `doc-review` actually ask for, then fixed what the record showed was wrong. No site content changes — this is all agent tooling. ## Why `doc-review` produced **0 Critical, 5 Improvement and ~20 Suggestion** findings across those 14 PRs. Its genuinely valuable catches were all cross-file consistency checks the skill never asked for: - a changelog entry documenting `kosli update attestation-type`, a command with no reference page (#371) - `template-reference/flow_template.md` out of sync with the schema the same PR regenerated (#296) - the one file an approvals-removal sweep missed, `understand_kosli/how_kosli_works.md:22` (#345) Its weakest findings were prose polish, some already fixed at branch head. Meanwhile its written checklist was dominated by things that always pass or are already enforced by `vale-spellcheck`. Two structural gaps the PR record made obvious: - **Placement was never questioned.** In #305 a pure reference page was authored into `integrations/`, and a human reviewer had to ask for the move — commit `9e7a121 docs: move GitHub Action reference into the Reference section`. That question should come from the review. - **Generated pages were handled inconsistently.** #375 got it right and said so. #374 wrote *"the durable fix is in the `kosli-dev/cli` generator — a hand-edit here is overwritten by the next release"* and then emitted a `Fix this` link scoped to `repo=kosli-dev/docs` telling an agent to edit the generated file anyway, plus 4 inline comments on regenerated files. ## What changed **`doc-review`** — promoted the three accidental wins to named checks, each carrying its precedent. Added placement, redirects and anchor stability. Added an explicit *what not to report* bar and an 8-finding cap. Stopped hand-checking spelling. Dropped the "what looks good" recital that the sticky comment re-renders on every push. **Generated pages** — split into three categories rather than one blanket ban: deterministically regenerated (edit is deleted), agent-synced (edit survives but drifts), and hand-authored despite the directory (`client_reference/overview.md`, `output_and_verbosity.md`). Includes the filename→source mapping, verified upstream: `kosli_attest_sonar.md` ← `cmd/kosli/attestSonar.go`. Also records that **`^` is the CLI's backtick convention** in Go long descriptions, substituted by `kosli docs`. That makes the `^jq^` defect #374 found a generator escaping bug in the Accordion-title path, not a typo in the Go string — so a reviewer can point at the right fix. Worth filing upstream separately. **`doc-write`** — added a Diátaxis→tab placement table so #305 can't recur, plus redirects, anchor stability, and the generated-paths table. **New `doc-structure` skill + monthly workflow** — audits navigation shape and changelog coverage, which per-PR review structurally cannot see, and files issues. Read-only against docs; issues are its only write. Capped at 8 issues, deduplicating against open issues first — its headline check reproduces the `/getting_started/attestations` summary gap, which is already open as #364. **New `scripts/audit_navigation.py` + 22 tests** — the audit's mechanical checks, extracted from an inline heredoc. Three payoffs: 1. `pr-quality.yml` already runs `pytest tests/`, so **CLAUDE.md core rule 2 is now enforced deterministically** — a page file with no `navigation` entry fails the build. No new job needed. 2. `doc-structure.yml` can allow `Bash(python3 scripts/audit_navigation.py:*)` instead of `Bash(python3:*)`, which was arbitrary code execution. 3. Determinism. The inline version had already shipped a bug: `sed 's|\.mdx\?$||'` is a no-op on BSD sed, so every page looked orphaned on macOS. That case is now a regression test. Integrity findings (orphans, dangling entries) are separated from shape findings (single-child groups, deep nesting, Title Case labels, oversized groups, inconsistent icons). Only integrity can fail a build — the script cannot tell a group that should be merged from one deliberately kept separate. `Reference ▸ CLI Reference` is exempt from shape checks: `update-cli-nav.py` generates it from the CLI's command tree, so a single-child `kosli allow` group is upstream truth. Without that exemption the audit reported 54 findings, 21 of them proposing to reshape generated navigation — the same mistake being fixed in `doc-review`. It now reports 33, all hand-maintained. **New `docs-restructure` issue template** — Markdown, not a YAML form: `gh issue create --body` doesn't apply templates mechanically and YAML forms can't be filled from the CLI, so a form would help humans and do nothing for the job. Its URL-impact section encodes the distinction that decides whether a restructure is safe — a group rename changes no URLs, a moved page file needs a `config/redirects.json` entry. `config.yml` keeps blank issues enabled. **`CLAUDE.md`** — documented the six automated PR checks, the generated-page source map, the audit script, and the three skills. Removed the pointer to a `changelog-creator` skill that doesn't exist in this repo. ## Anti-rot pass Swept all three skills for dated claims. Counts ("three of the last fourteen PRs") and current-state assertions ("link-rot reports skipping on most PRs") became durable rules. The link-rot guidance now routes through `gh pr checks` so it self-heals if Mintlify starts running it reliably. Past-tense `Precedent:` items were kept — they're what make the checks concrete. ## Verification - `python3 -m pytest tests/` — 44 passed (22 pre-existing + 22 new) - `python3 scripts/audit_navigation.py --check` — exit 0, integrity clean - `mint broken-links` — no new broken links - Both workflows parse; triggers and permissions confirmed ## Follow-ups, not in this PR - `tutorials/working_with_controls.mdx:24` links to `/getting_started/service-accounts`, which has never existed — the page is `/administration/authentication/service_accounts`. Broken on `main` since #154; `link-rot` reports `skipping`, which is why it went unseen. - The `mintlify-docs` plugin in `kosli-plugins` still ships near-duplicate `doc-writer`/`doc-reviewer` agents that say "update `docs.json` navigation" — the pre-`config/` layout. Needs its own PR there. - The reviews twice asked for `python3` in `doc-review.yml`'s `--allowedTools` to validate JSON payloads and fence balance. Left alone — `Bash(python3:*)` is a security-surface call worth making deliberately.
gsavage
pushed a commit
that referenced
this pull request
Sep 7, 2026
Reviewed the last 20 non-bot PRs (14 touched docs) against what `doc-write` and `doc-review` actually ask for, then fixed what the record showed was wrong. No site content changes — this is all agent tooling. ## Why `doc-review` produced **0 Critical, 5 Improvement and ~20 Suggestion** findings across those 14 PRs. Its genuinely valuable catches were all cross-file consistency checks the skill never asked for: - a changelog entry documenting `kosli update attestation-type`, a command with no reference page (#371) - `template-reference/flow_template.md` out of sync with the schema the same PR regenerated (#296) - the one file an approvals-removal sweep missed, `understand_kosli/how_kosli_works.md:22` (#345) Its weakest findings were prose polish, some already fixed at branch head. Meanwhile its written checklist was dominated by things that always pass or are already enforced by `vale-spellcheck`. Two structural gaps the PR record made obvious: - **Placement was never questioned.** In #305 a pure reference page was authored into `integrations/`, and a human reviewer had to ask for the move — commit `9e7a121 docs: move GitHub Action reference into the Reference section`. That question should come from the review. - **Generated pages were handled inconsistently.** #375 got it right and said so. #374 wrote *"the durable fix is in the `kosli-dev/cli` generator — a hand-edit here is overwritten by the next release"* and then emitted a `Fix this` link scoped to `repo=kosli-dev/docs` telling an agent to edit the generated file anyway, plus 4 inline comments on regenerated files. ## What changed **`doc-review`** — promoted the three accidental wins to named checks, each carrying its precedent. Added placement, redirects and anchor stability. Added an explicit *what not to report* bar and an 8-finding cap. Stopped hand-checking spelling. Dropped the "what looks good" recital that the sticky comment re-renders on every push. **Generated pages** — split into three categories rather than one blanket ban: deterministically regenerated (edit is deleted), agent-synced (edit survives but drifts), and hand-authored despite the directory (`client_reference/overview.md`, `output_and_verbosity.md`). Includes the filename→source mapping, verified upstream: `kosli_attest_sonar.md` ← `cmd/kosli/attestSonar.go`. Also records that **`^` is the CLI's backtick convention** in Go long descriptions, substituted by `kosli docs`. That makes the `^jq^` defect #374 found a generator escaping bug in the Accordion-title path, not a typo in the Go string — so a reviewer can point at the right fix. Worth filing upstream separately. **`doc-write`** — added a Diátaxis→tab placement table so #305 can't recur, plus redirects, anchor stability, and the generated-paths table. **New `doc-structure` skill + monthly workflow** — audits navigation shape and changelog coverage, which per-PR review structurally cannot see, and files issues. Read-only against docs; issues are its only write. Capped at 8 issues, deduplicating against open issues first — its headline check reproduces the `/getting_started/attestations` summary gap, which is already open as #364. **New `scripts/audit_navigation.py` + 22 tests** — the audit's mechanical checks, extracted from an inline heredoc. Three payoffs: 1. `pr-quality.yml` already runs `pytest tests/`, so **CLAUDE.md core rule 2 is now enforced deterministically** — a page file with no `navigation` entry fails the build. No new job needed. 2. `doc-structure.yml` can allow `Bash(python3 scripts/audit_navigation.py:*)` instead of `Bash(python3:*)`, which was arbitrary code execution. 3. Determinism. The inline version had already shipped a bug: `sed 's|\.mdx\?$||'` is a no-op on BSD sed, so every page looked orphaned on macOS. That case is now a regression test. Integrity findings (orphans, dangling entries) are separated from shape findings (single-child groups, deep nesting, Title Case labels, oversized groups, inconsistent icons). Only integrity can fail a build — the script cannot tell a group that should be merged from one deliberately kept separate. `Reference ▸ CLI Reference` is exempt from shape checks: `update-cli-nav.py` generates it from the CLI's command tree, so a single-child `kosli allow` group is upstream truth. Without that exemption the audit reported 54 findings, 21 of them proposing to reshape generated navigation — the same mistake being fixed in `doc-review`. It now reports 33, all hand-maintained. **New `docs-restructure` issue template** — Markdown, not a YAML form: `gh issue create --body` doesn't apply templates mechanically and YAML forms can't be filled from the CLI, so a form would help humans and do nothing for the job. Its URL-impact section encodes the distinction that decides whether a restructure is safe — a group rename changes no URLs, a moved page file needs a `config/redirects.json` entry. `config.yml` keeps blank issues enabled. **`CLAUDE.md`** — documented the six automated PR checks, the generated-page source map, the audit script, and the three skills. Removed the pointer to a `changelog-creator` skill that doesn't exist in this repo. ## Anti-rot pass Swept all three skills for dated claims. Counts ("three of the last fourteen PRs") and current-state assertions ("link-rot reports skipping on most PRs") became durable rules. The link-rot guidance now routes through `gh pr checks` so it self-heals if Mintlify starts running it reliably. Past-tense `Precedent:` items were kept — they're what make the checks concrete. ## Verification - `python3 -m pytest tests/` — 44 passed (22 pre-existing + 22 new) - `python3 scripts/audit_navigation.py --check` — exit 0, integrity clean - `mint broken-links` — no new broken links - Both workflows parse; triggers and permissions confirmed ## Follow-ups, not in this PR - `tutorials/working_with_controls.mdx:24` links to `/getting_started/service-accounts`, which has never existed — the page is `/administration/authentication/service_accounts`. Broken on `main` since #154; `link-rot` reports `skipping`, which is why it went unseen. - The `mintlify-docs` plugin in `kosli-plugins` still ships near-duplicate `doc-writer`/`doc-reviewer` agents that say "update `docs.json` navigation" — the pre-`config/` layout. Needs its own PR there. - The reviews twice asked for `python3` in `doc-review.yml`'s `--allowedTools` to validate JSON payloads and fence balance. Left alone — `Bash(python3:*)` is a security-surface call worth making deliberately.
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Approvals are being retired (kosli-dev/server#5125). CLI v2.35.0 removed the approval commands and server kosli-dev/server#6309 removed the approval API, which is now in prod.
The
update-cli-docsworkflow already deleted the five generatedclient_referencepages and their nav entries in #343. This PR covers everything that automation cannot do.Changes
config/redirects.jsongets the five deletedclient_reference/kosli_*approval*URLs pointing at/client_reference/overview. The workflow deletes pages but never touches redirects, so those URLs were 404ing for bookmarks and search hits.tutorials/cli_and_http_proxy.md— removed thekosli request approvalexample; the page still shows two proxy examples.integrations/kosli_actions.md— the documented custom-webhook payload now matchesMessageProvider._webhook_base_payload: dropped theapprovalsarray, and thedeploymentsarray with it (the builder emits neither, and thedeploymentscollection was dropped long ago — stale independently of #5125).administration/managing_users/roles_in_kosli.md— removed the permission-matrix row and the four per-role bullets.understand_kosli/glossary.md/controls.md—approvalwas never a built-in attestation type; the built-ins aregeneric,junit,snyk,pull_request,jira,sonar.kosli get traillive example — repointed from the pinned March 2024 trail (which containsartifact_approval_reportedevents) toe4757683b74df7033c95aa544a7824b395c2f8bb(July 2026, 16 events, no approvals), and regenerated the page. Since the page is generated, pinning a newer trail is the only way to stop the approval events reappearing on every CLI release.kosli report approvalmodifier entry and moved the two tests that used it as their fixture onto commands that still exist.Test plan
pytest tests/— 22 passedpython scripts/test_update_cli_nav.py— PASSmint broken-links— no new breakages (the one hit,/getting_started/service-accountsintutorials/working_with_controls.mdx, is pre-existing and untouched here)rg -in approvalsweep — only concept/PR-approval prose and thehas-approvalpolicy name remainLive-docs test fixtures were deliberately left unrefreshed: regenerating them rewrites all five files with fresh live data and the suite passes without it.
🤖 Generated with Claude Code