Skip to content

chore(brand): em-dash sweep + scorecard publish_results fix#16

Merged
amcheste merged 1 commit into
developfrom
brand/align
May 11, 2026
Merged

chore(brand): em-dash sweep + scorecard publish_results fix#16
amcheste merged 1 commit into
developfrom
brand/align

Conversation

@amcheste-ai-agent
Copy link
Copy Markdown
Contributor

Summary

Brand-alignment pass against the alanchester-brand voice rules, plus a workflow fix for the OpenSSF Scorecard badge.

1. Em-dash sweep (12 files, 177 dashes)

Mechanical replacement of with . and capitalization of the following letter when it was lowercase. Code blocks and markdown table rows protected. Same approach as claude-teams-operator#224.

File Em-dashes swept
README.md 14
CONTRIBUTING.md 10
CLAUDE.md 2
CHANGELOG.md 1
docs/design/claude-bot-account.md 25
docs/tooling/dev-tooling-stack.md 11
docs/workflows/ci-automation.md 31
docs/workflows/branching-and-releases.md 16
docs/philosophies/branching-strategy.md 14
docs/philosophies/release-cadence.md 11
docs/philosophies/testing.md 20
docs/philosophies/security-posture.md 22

Post-sweep grep -nE '\. [a-z]' audit produced 5 matches, all abbreviation false positives (e.g., i.e., E.g.) left as-is.

2. Scorecard publish_results fix

The OpenSSF Scorecard badge on the README was returning 404 from the public API. Root cause: this repo's default branch is develop (intentional, until a stable first release switches default to main), but the workflow only published Scorecard results when github.ref == 'refs/heads/main'. Scheduled runs were succeeding on develop but never publishing.

Verified by direct API query before the fix: curl api.securityscorecards.dev/projects/github.com/amcheste/engineering-handbook returned HTTP 404.

The fix

.github/workflows/scorecard.yml (3 lines):

   push:
-    branches: [main]
+    branches: [main, develop]

           results_format: sarif
-          publish_results: ${{ github.ref == 'refs/heads/main' }}
+          publish_results: ${{ github.ref_name == github.event.repository.default_branch }}

       - uses: github/codeql-action/upload-sarif@d4b3ca9fa7f69d38bfcd667bdc45bc373d16277e # v4
-        if: github.ref == 'refs/heads/main'
+        if: github.ref_name == github.event.repository.default_branch

Why this works across your develop-then-main lifecycle

Phase Default Schedule on publish_results Result
Pre-first-release (now) develop develop develop == develop publishes from develop
First stable release; default switches to main main main main == main publishes from main; auto-transitions
Steady state (main = releases, develop = integration) main main main publishes, develop pushes don't clean: public score == release state

github.event.repository.default_branch resolves dynamically per run, so no workflow edit needed when you flip the default branch in GitHub Settings. Brief lag (up to one Monday cycle) on the badge after a default-branch switch; self-heals.

What this PR does NOT include

  • Repo topics — currently null. Adding engineering, handbook, philosophies, workflows, ai-amplified, software-practices via gh repo edit is a manual public-state change, flagged for separate action.
  • Banner — README has no banner image. A Claude Design prompt has been drafted for separate use. Banner will land in a follow-up PR after the design session.
  • The same scorecard publish_results bug in repo-template — propagating the fix there is queued as a follow-up so future repos born from the template don't inherit the bug.
  • claude-teams-operator's scorecard failure — different cause (imposter-commit pin on github/codeql-action/upload-sarif), queued as a follow-up there.

Verification

  • git diff develop --name-only → 13 files. No edits outside docs/, root prose, or .github/workflows/scorecard.yml.
  • Em-dash sweep: 177 removed, 5 abbreviation false positives remaining (documented).
  • Scorecard fix: 3 lines in one file. No other workflow changes.

🤖 Generated with Claude Code

Two changes from an alanchester-brand audit pass.

1. Em-dash sweep across 12 prose files (177 dashes removed).
   Mechanical replacement of ` — ` with `. ` and capitalization of
   the following letter when it was lowercase. Code blocks and
   markdown table rows protected from substitution. Post-sweep
   audit produced 5 matches, all abbreviation false positives
   (e.g., i.e., E.g.) left as-is.

   Files swept:
     README.md, CONTRIBUTING.md, CLAUDE.md, CHANGELOG.md,
     docs/design/claude-bot-account.md,
     docs/tooling/dev-tooling-stack.md,
     docs/workflows/ci-automation.md,
     docs/workflows/branching-and-releases.md,
     docs/philosophies/{branching-strategy,release-cadence,
       testing,security-posture}.md.

2. .github/workflows/scorecard.yml: fix publish_results gating
   so the OpenSSF Scorecard badge actually populates.

   Before: publish_results only fired on `refs/heads/main`. This
   repo's default branch is `develop` (intentional, until a stable
   first release switches default to main). Scheduled runs fired
   on develop and succeeded but never published. Badge returned
   404 from the Scorecard API.

   After: publish_results uses `github.ref_name ==
   github.event.repository.default_branch`. Works through the
   develop-then-main lifecycle without further code changes; the
   workflow tracks whatever the GitHub default branch is set to.
   Also added develop to the push triggers so pushes to develop
   re-run the analysis (publish gate still keeps the score
   canonical to default).

   The same pattern bug lives in repo-template's scorecard.yml;
   propagating the fix there is queued as a follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: amcheste <13696614+amcheste@users.noreply.github.com>
@amcheste amcheste merged commit 9063c3c into develop May 11, 2026
6 checks passed
@amcheste amcheste deleted the brand/align branch May 11, 2026 22:04
amcheste added a commit to amcheste/mac-dev-setup that referenced this pull request May 12, 2026
## Summary

Brand-alignment pass against the [alanchester-brand voice rules](https://github.com/amcheste/alanchester-brand/blob/main/docs/voice.md). 105 em-dashes addressed across 7 prose files, plus the now-standard Scorecard `publish_results` fix.

## 1. Em-dash sweep (7 files, 105 dashes addressed)

| File | Em-dashes |
|---|---|
| README.md | 33 |
| CONTRIBUTING.md | 11 |
| CLAUDE.md | 20 |
| TESTING.md | 27 |
| VERSIONING.md | 8 |
| CHANGELOG.md | 4 |
| SECURITY.md | 2 |

**87 swept mechanically** via `re.sub(r' — ([a-z])', lambda: '. ' + capitalize, ...)` with code-block and table-row protection. Same approach as [engineering-handbook PR #16](amcheste/engineering-handbook#16) and [claude-teams-operator PR #228](amcheste/kagents#228).

**18 swept manually** with contextual judgment:
- Mid-table appositives (`X — Y` where Y describes X) → commas. E.g. `pyenv — switch versions` → `pyenv, switch versions`.
- Longer table-cell continuations → period + capitalize. E.g. `Persist facts across sessions — supplements CLAUDE.md` → `Persist facts across sessions. Supplements CLAUDE.md.`
- List-introducing em-dashes → colons. E.g. `Breaking changes — tools removed, ...` → `Breaking changes: tools removed, ...`
- Stable-state appositives → semicolons. E.g. `Pre-stable — actively being developed` → `Pre-stable; actively being developed`.
- Two end-of-line em-dashes in CLAUDE.md (`...productive —\ntools, dotfiles...`) → commas with continuation.

**One em-dash deliberately preserved**: `TESTING.md:73` (`# Dry run — show what would execute without running`) is inside a `` ```bash `` code block (a shell comment example for `act --dryrun`). Per theming-prompt rules on code structure, this stays.

**Post-sweep audit clean**: 1 match on `grep -nE '\. [a-z]'` — `README.md:149` "Region (e.g. iad): iad" — abbreviation false positive (`e.g.`), left as-is.

## 2. Scorecard publish_results fix

Same one-pattern fix as engineering-handbook, repo-template, and claude-teams-operator:

```diff
   push:
-    branches: [main]
+    branches: [main, develop]

           results_format: sarif
-          # Only publish to scorecard.dev from main — the action enforces this
-          publish_results: ${{ github.ref == 'refs/heads/main' }}
+          # Publish to scorecard.dev only from the default branch.
+          publish_results: ${{ github.ref_name == github.event.repository.default_branch }}

       - uses: github/codeql-action/upload-sarif@... # v4
-        if: github.ref == 'refs/heads/main'
+        if: github.ref_name == github.event.repository.default_branch
```

This repo's default is currently `main`, so no behavior change today. But the workflow is now correct regardless of which branch is set as default — consistent with the family pattern and forward-compatible if you ever flip to develop as default for a pre-stable-release phase.

## Note on the codeql-action SHA

The `github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7` pin on develop is **real and correct** — verified via the GitHub API. No imposter-commit issue on develop.

`main` still has the older imposter SHA (`d4b3ca9f...` from when it was last updated from repo-template). That'll resolve on its own at the next release promotion (`develop → main`), since develop already has the real SHA.

## What's NOT in this PR

- **Banner migration** (`assets/logo.png` → `assets/banner.svg` per banner-spec). Same follow-up as pokemon-red-ai, overleaf-mcp, etc.
- **Repo topics** (`repositoryTopics: null`). Manual `gh repo edit`.

## Verification

- [x] `git diff origin/develop --name-only` → 8 files. No edits to `setup.sh`, `Brewfile*`, `Formula/`, `claude-skills/`, `dotfiles/`, or `scripts/`.
- [x] `grep -rn "—" *.md` → 1 result (TESTING.md:73, shell-comment example in code block).
- [x] Em-dashes in newly-rewritten prose: 0.
- [x] Em-dashes in code blocks / shell comments: preserved.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
amcheste added a commit that referenced this pull request May 12, 2026
## Summary

Follow-up to [PR #16](#16). The `publish_results` fix in #16 will let the Scorecard workflow try to publish on the next Monday scheduled run (the first time this repo has published since the develop-default branch was set). But the pinned SHA on `github/codeql-action/upload-sarif` is an imposter commit per OSSF Scorecard's anti-supply-chain check, so the publish would fail at the SARIF upload step with:

```
imposter commit: d4b3ca9fa7f69d38bfcd667bdc45bc373d16277e
does not belong to github/codeql-action/upload-sarif
```

(Already verified failing on `claude-teams-operator` for the same reason since at least 2026-04-29.)

## Fix

```diff
-      - uses: github/codeql-action@d4b3ca9 # v4
+      - uses: github/codeql-action@68bde55 # v4
```

The new SHA is the real v4 tag commit, verified via:
```
gh api repos/github/codeql-action/git/refs/tags/v4
→ tag object SHA 5e316336eb4f107009e477d4bfbfff13d7250fae
gh api repos/github/codeql-action/git/tags/5e316336eb4f107009e477d4bfbfff13d7250fae
→ object: { type: commit, sha: 68bde559dea0fdcac2102bfdf6230c5f70eb485e }
```

## Cross-repo status

The same imposter SHA propagated from `repo-template` into every repo born from it. Companion fixes:
- `repo-template` — [PR #11](amcheste/repo-template#11) (open, includes both publish_results + SHA fixes)
- `claude-teams-operator` — [PR #228](amcheste/kagents#228) (open, includes table-cell em-dash sweep + scorecard fixes)

## Verification

- [x] `git diff develop --name-only` → exactly `.github/workflows/scorecard.yml`.
- [x] 1-line change.

No-Linear-Issue: follow-up to PR #16, propagating cross-family scorecard SHA fix

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants