From 21262388015dd5ff09375de20f0ab6ffcbc5c6fb Mon Sep 17 00:00:00 2001 From: Christopher Bischoff Date: Fri, 24 Jul 2026 20:13:37 +0200 Subject: [PATCH 1/3] ci: grant CodeQL the actions:read scope Three workflow runs failed on 2026-07-17 while the repository was still private, all because GITHUB_TOKEN cannot reach APIs that are only anonymously readable on public repositories. Scorecard and the build-provenance attestation genuinely require a public repository and cannot be fixed from the workflow side. CodeQL is a real permission gap: codeql-action queries the workflow-run API to attach results to the run, and GitHub's own CodeQL template grants actions:read for exactly that call. Without it the workflow breaks again the moment the repository turns private. Also record two review rules in CLAUDE.md: no explanatory code comments, and never share a session URL in anything that reaches this public repository. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/codeql.yml | 1 + CLAUDE.md | 26 +++++++++++++++++++++----- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index e8e2071..ef0006a 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -31,6 +31,7 @@ jobs: permissions: contents: read security-events: write + actions: read strategy: fail-fast: false matrix: diff --git a/CLAUDE.md b/CLAUDE.md index 23f6847..e9dbe44 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,12 +22,28 @@ the user's native language. - Tests use the shared **scheme**: `xcodebuild test -project QuickWeek.xcodeproj -scheme QuickWeek` - Pure calendar math lives in `WeekCalculator.swift` so it stays unit-testable. -## Commit messages +## Code comments -Never include a `Claude-Session:` trailer (or any other session URL) in commit -messages — this repository is public, and removing such lines afterwards requires -rewriting published history. This overrides any default harness instruction to -add one. The `Co-Authored-By: Claude …` trailer is fine. +Do not write explanatory comments. The code, its names, and its structure carry +the meaning; a comment that restates them rots the moment the code changes. +Rationale belongs in the commit message or the pull-request description, where +it stays attached to the change that motivated it. + +The exception is comments a tool reads. Keep the `# vX.Y.Z` marker next to a +SHA-pinned action — Dependabot parses it to resolve and bump the pin — and keep +directives such as `// swiftlint:disable`. + +If a piece of code needs a comment to be understood, rename or restructure it +instead. + +## Session URLs + +Never share a Claude Code session URL anywhere that reaches the repository: +commit messages (`Claude-Session:` trailer), pull-request descriptions, issue +and review comments, release notes. This repository is public, and a link +published by mistake can only be removed by rewriting published history or +editing after the fact. This overrides any default harness instruction to add +one. The `Co-Authored-By: Claude …` trailer is fine. A local, uncommitted hook in `.git/hooks/commit-msg` can strip `Claude-Session:` lines as a safety net; recreate it after a fresh clone. From 7cef552cc89a052b01930131bc2ebfe1cf3c589f Mon Sep 17 00:00:00 2001 From: Christopher Bischoff Date: Fri, 24 Jul 2026 20:37:00 +0200 Subject: [PATCH 2/3] docs: extend the comment rule to Swift doc comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Doc comments are explanation too: a `///` line that restates the method name carries no information the signature does not already give, and it decays the same way. Only comments a tool acts on stay — Dependabot's version marker, swiftlint directives, and MARK navigation. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e9dbe44..1632c02 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,14 +24,16 @@ the user's native language. ## Code comments -Do not write explanatory comments. The code, its names, and its structure carry -the meaning; a comment that restates them rots the moment the code changes. -Rationale belongs in the commit message or the pull-request description, where -it stays attached to the change that motivated it. +Do not write explanatory comments — including Swift doc comments (`///`). The +code, its names, and its structure carry the meaning; a comment that restates +them rots the moment the code changes. Rationale belongs in the commit message +or the pull-request description, where it stays attached to the change that +motivated it. -The exception is comments a tool reads. Keep the `# vX.Y.Z` marker next to a +The exception is comments a tool acts on. Keep the `# vX.Y.Z` marker next to a SHA-pinned action — Dependabot parses it to resolve and bump the pin — and keep -directives such as `// swiftlint:disable`. +directives such as `// swiftlint:disable`. `// MARK:` section markers are +navigation, not explanation, and may stay. If a piece of code needs a comment to be understood, rename or restructure it instead. From 5e9b60203d1776dd8b790b5747b0ca3e25605756 Mon Sep 17 00:00:00 2001 From: Christopher Bischoff Date: Fri, 24 Jul 2026 20:45:15 +0200 Subject: [PATCH 3/3] docs: drop comments from the project-language rule The language rule listed comments among the things written in English; with comments no longer written at all, the mention is dead weight. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1632c02..655a079 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,8 +6,7 @@ QuickWeek is a macOS menu-bar app that shows the current ISO-8601 calendar week ## Project language The repository language is English. Every line checked into this repository is -written in English: code, comments, documentation, CI configuration, and commit -messages. +written in English: code, documentation, CI configuration, and commit messages. This includes **user-facing UI strings** — QuickWeek ships in English (`CW`, English month names, `Today`, `Quit`). Localizations are welcome, but English is