security: enable GitHub security defaults (secret scanning, branch protection, dependabot) across PsychQuant org repos

[kiki830621]

Problem

From verification of #78 (#78 verify report, finding #2):
「All 3 new repos have secret scanning, branch protection, dependabot, push protection all DISABLED. Org-wide pattern (same as ooxml-swift/word-to-md-swift etc), not a #78 regression but #78 widens the surface.」
— Source: security reviewer, 2026-04-18

The 3 repos extracted by #78 (note-core-swift, note-to-pdf-swift, note-to-html-swift) have zero GitHub security hardening enabled:

gh api /repos/PsychQuant/note-core-swift/security_and_analysis  # → all flags off
gh api /repos/PsychQuant/note-core-swift/branches/main/protection  # → 404

This is not a #78 regression — every PsychQuant org repo (ooxml-swift, word-to-md-swift, common-converter-swift, marker-swift, markdown-swift, word-builder-swift, etc.) has the same posture. #78 widens the attack surface by 3 repos but did not introduce the gap.

Type

enhancement

Expected

For all PsychQuant/* Swift package repos consumed by macdoc (or any production project), the following defaults SHALL be enabled:

• Secret scanning (free for public repos)
• Push protection for secrets
• Dependabot alerts + security updates
• Branch protection on main:
  • Require pull request before merging (or at minimum, prohibit force-push)
  • Require status checks if CI exists
• Optional: required signed commits

Actual

Repo	Secret scan	Push protection	Dependabot	Branch protection
note-core-swift	❌	❌	❌	❌
note-to-pdf-swift	❌	❌	❌	❌
note-to-html-swift	❌	❌	❌	❌
ooxml-swift	❌	❌	❌	❌
word-to-md-swift	❌	❌	❌	❌
word-builder-swift (just shipped)	❌	❌	❌	❌
common-converter-swift	❌	❌	❌	❌
(others ...)	likely all ❌	likely all ❌	likely all ❌	likely all ❌

Strategy

• Audit all PsychQuant/* repos for current security posture (gh api .../security_and_analysis)
• Decide on org-level defaults vs per-repo settings
• Apply baseline (secret scanning + push protection + dependabot + main-branch protection) across all repos
• Document the standard in macdoc's CLAUDE.md or a separate SECURITY.md
• Add to release-flow checklist for new packages

Related

• Surfaced via refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 verification
• Affects supply-chain security posture for the entire macdoc ecosystem

---

Current Status

Phase: closed
Last updated: 2026-04-21 by idd-update (post-close auto-sync)

Key Decisions

• (2026-04-21) Closed via /idd-close: closing comment at #issuecomment-4287092071; all Strategy checkboxes + Diagnosis Phase-1-4 checklist resolved ([x] done, [-] 2FA won't-fix + per-repo SECURITY.md rejected, [~] private-repo branch protection scoped-out); Gate Check passed.
• (2026-04-21) Spectra archive: openspec/changes/archive/2026-04-21-psychquant-security-defaults/; new capability spec repository-security-baseline with 8 ADDED requirements now lives at openspec/specs/repository-security-baseline/spec.md.
• (2026-04-21) 52 repos audited all-green: 39 public full baseline + 14 private alerts-only; ./scripts/audit-security.sh exit 0.
• (2026-04-21) Private-repo branch protection unavailable on free tier (GitHub Pro required) — spec + SECURITY.md + audit tool updated to mark as expected-out-of-scope.
• (2026-04-19) Org defaults don't auto-propagate on free-tier orgs — release-flow gate in common-release-flow.md is load-bearing for new packages.
• (2026-04-19) markdown-swift Dependabot smoke: 0 auto-PRs in 48hr → clean dep tree, safe bulk rollout.
• (2026-04-19) Complexity = SDD-warranted → /spectra-discuss resolved 7 open questions before /spectra-propose.

Scope Changes

• Added macdoc itself to Phase-2 target list (original spec omitted the umbrella).
• Private-repo baseline reduced from "alerts + branch protection" to "alerts only" due to free-tier GitHub Pro constraint.
• Per-repo SECURITY.md copies rejected in favour of single canonical file at macdoc root (per design Non-Goals).
• 2FA org-wide enforcement explicitly scoped out (per Non-Goals).

Blocking

• (none — issue closed; working-tree files awaiting commit but not blocking)

Commits

• (none yet referencing security: enable GitHub security defaults (secret scanning, branch protection, dependabot) across PsychQuant org repos #80 — macdoc/SECURITY.md, macdoc/scripts/audit-security.sh, target lists, macdoc/openspec/specs/repository-security-baseline/spec.md, archived Spectra change at macdoc/openspec/changes/archive/2026-04-21-psychquant-security-defaults/, and modified ~/Developer/che-claude-config/rules/common-release-flow.md are all uncommitted working-tree changes.)
• External effects (config-only, no commits): PsychQuant org 5 flags flipped; 39 public repos hardened; 14 private repos have Dependabot alerts enabled.

[kiki830621]

Diagnosis

Type

enhancement / refactor（infra config — org + per-repo 安全 posture）

Current state (verified 2026-04-19)

Org-level（PsychQuant）— 所有 default 皆 OFF

{
  "secret_scanning_enabled_for_new_repositories": false,
  "secret_scanning_push_protection_enabled_for_new_repositories": false,
  "dependabot_alerts_enabled_for_new_repositories": false,
  "dependabot_security_updates_enabled_for_new_repositories": false,
  "dependency_graph_enabled_for_new_repositories": false,
  "two_factor_requirement_enabled": false,
  "advanced_security_enabled_for_new_repositories": false
}

→ 新開的 repo 完全沒有安全 hardening。

Per-repo（實際 posture，已稽核 14 個 macdoc-chain Swift repos）

Repo	Branch protection (main)	Dependabot alerts	Dep security updates	Secret scan	Push protection
macdoc	有（req_reviews=0，force-push 禁止）	✅ ON	❌ OFF	404	404
ooxml-swift	有（req_reviews=0）	✅ ON	❌ OFF	404	404
common-converter-swift	有（req_reviews=0）	✅ ON	❌ OFF	404	404
word-to-md-swift	有（req_reviews=0）	✅ ON	❌ OFF	404	404
markdown-swift	有（req_reviews=0）	✅ ON	❌ OFF	404	404
marker-swift	有（req_reviews=0）	✅ ON	❌ OFF	404	404
biblatex-apa-swift	有（req_reviews=0）	✅ ON	❌ OFF	404	404
che-word-mcp	有（req_reviews=0）	✅ ON	❌ OFF	404	404
che-pdf-mcp	有（req_reviews=0）	✅ ON	❌ OFF	404	404
pdf-to-latex-swift	❌ 無	✅ ON	❌ OFF	404	404
note-to-pdf-swift	❌ 無	✅ ON	❌ OFF	404	404
note-to-html-swift	❌ 無	✅ ON	❌ OFF	404	404
word-builder-swift	❌ 無	?	❌ OFF	404	404
ocr-swift	❌ 無	?	❌ OFF	404	404

Analysis — 校正 #78 verify 的原始描述：

• Dependabot alerts（vulnerability alerts endpoint）實際上在老 repos 上已 ON — 不是 issue body 說的全 ❌
• Secret scanning / push protection 的確全部未啟用（404 on security_and_analysis）
• Branch protection 是 regression：2026-03 後的新 extractions（pdf-to-latex-swift、note-*、word-builder-swift、ocr-swift）完全沒 protection；較舊的 repos 至少有 "shell" protection（force-push 禁止、req_reviews=0）
• 2FA org-wide requirement OFF — 帳號被盜即可推 main
• Dependabot security updates（自動 PR 修 CVE）全部 OFF — 有 alert 但沒自動修

Impact

• 影響 repos：~37 public Swift/TeX repos + 14 private（共 ~51 目標）
• 影響使用者流程：
  • macdoc 依賴鏈 12 個 Swift 套件的 supply-chain 風險（私鑰/API key commit、已知 CVE 未修、main 被污染）
  • 新開 repo 每次都要手動開 6 項設定（人類會漏）
• Blast radius：macdoc 作為 CLI + MCP 入口，任何上游 supply-chain compromise 會直接影響使用者 ~/bin/macdoc 與 Claude Code MCP calls

Strategy

分階段 rollout，每階段可獨立驗收：

Phase 1 — Org defaults + critical 2FA 決策

• 設定 org.secret_scanning_enabled_for_new_repositories = true
• 設定 org.secret_scanning_push_protection_enabled_for_new_repositories = true
• 設定 org.dependabot_alerts_enabled_for_new_repositories = true
• 設定 org.dependabot_security_updates_enabled_for_new_repositories = true
• 設定 org.dependency_graph_enabled_for_new_repositories = true
• [-] 決策：two_factor_requirement_enabled 開不開？（需 discuss — 影響 collaborators 登入） — decision: NO 2FA enforcement per Non-Goals (org has 5 collaborators; friction > marginal benefit on solo-led org; personal 2FA already in place)

Phase 2 — macdoc-chain retroactive hardening（12 repos 優先）

• 對 common-converter-swift / word-to-md-swift / word-builder-swift / pdf-to-latex-swift / ocr-swift / note-core-swift / note-to-pdf-swift / note-to-html-swift / ooxml-swift / markdown-swift / marker-swift / biblatex-apa-swift：
  • 啟 secret scanning + push protection（public 免費）
  • 啟 dependabot security updates
  • 套 branch protection：至少 allow_force_pushes=false、allow_deletions=false、required_linear_history=true
• 驗：重跑 audit script 確認 matrix 轉綠

Phase 3 — 其餘 PsychQuant Swift repos rollout

• 剩下 ~25 個 public Swift repos 套同樣 baseline
• [~] Private Swift repos（14 個）：只能套 dependabot + branch protection（secret scanning 要 GHAS license，free tier 私庫不支援） — partial: Dependabot alerts enabled on all 14 private repos; branch protection N/A on free tier (GitHub Pro required); audit-security.sh marks as N/A(tier) not FAIL

Phase 4 — 制度化

• [-] 寫 SECURITY.md（template）到各核心 repo — rejected: single canonical SECURITY.md at macdoc root chosen instead (per Non-Goals: per-repo duplication would immediately drift)
• 更新 macdoc CLAUDE.md 或加 .claude/rules/common-release-flow.md 的 release 檢查清單
• 寫 scripts/audit-security.sh（類似我剛跑的稽核 loop）方便之後 drift check

Complexity

SDD-warranted。理由：

• ✅ Cross-cutting：跨 37+ public repos + 14 private（>= 3 repos）
• ✅ Architectural decisions：
  1. 2FA 是否強制（org-wide，影響所有 collaborators）
  2. Branch protection 嚴格度（req_reviews=0 vs 1，影響日常 squash-merge workflow）
  3. Private repos 策略（GHAS 付費 vs 只套 free features）
• ✅ 新外部制度產物：SECURITY.md template、audit-security.sh、release-flow checklist 更新
• ✅ Phased rollout — 4 phase，Phase 間有 validation 依賴

opt-out 不成立：至少 3 個 open decisions 需對齊後才能落 proposal。

Risks

1. 2FA 強制可能 lock 掉 collaborator → discuss 前先列出目前 5 個 collaborators（billing.collaborators=5）有沒有 2FA，避免 sudden lockout。Mitigation：先通知、設 grace period。

2. Branch protection 跟 /spectra-* squash-merge workflow 衝突 → 目前有 gh pr merge --squash --delete-branch pattern。若設 required_approving_review_count >= 1，單人 org 會卡死（你自己不能 approve 自己 PR）。Mitigation：Phase 2 只套 allow_force_pushes=false，不加 req_reviews。

3. Dependabot security updates 啟動後可能爆一批 auto-PR → 老套件 note-core-swift@0.1.3 / word-builder-swift@0.9.0 等可能有未修 transitive CVE。Mitigation：先在一個 repo 實驗，觀察 PR 數量再推到全部。

4. security_and_analysis endpoint 404 可能是權限問題，不是 feature-off → 稽核腳本需驗證（用 --jq 或 fallback check）。Mitigation：implement 時先重新稽核 confirm endpoint behavior。

5. Free tier 私庫無法套 secret scanning → apa-bib-*、PawSpace 等私庫只能走 partial hardening。需明確這不是 bug，是 tier 限制。Mitigation：Phase 3 明確分 public/private 兩組 rollout。

6. Org 全域 change（settings）需 owner 權限 → 若執行者不是 org owner 會 403。先確認 kiki830621 是 PsychQuant owner。

Open questions（for /spectra-discuss）

1. 2FA requirement — 開還是不開？開的話 grace period 多長？
2. Branch protection 嚴格度 — req_reviews=0 夠嗎？要不要加 required_linear_history？
3. Private repos 要不要付 GHAS license — 還是接受 partial hardening？
4. 單一 SECURITY.md（放 macdoc）vs 每 repo 複製一份 — 前者簡潔，後者 self-contained
5. Audit script 放哪裡 — macdoc scripts/ 還是獨立 che-claude-config/scripts/？
6. Rollout 順序 — Phase 2 的 12 個 repos 是全部一次做，還是分 batch（先 macdoc + ooxml 再其他）？
7. Verification criterion — 每個 repo 至少過哪 N 項才算 Phase 完成？

Next

Complexity = SDD-warranted（3+ open decisions，4-phase rollout）。建議走 /spectra-discuss。

[kiki830621]

Closing Summary

Problem

Every PsychQuant public repo had secret scanning, push protection, and Dependabot security updates disabled; newer 2026-03+ extractions (pdf-to-latex-swift, ocr-swift, word-builder-swift, note-*) additionally had no main branch protection at all; org-level *_enabled_for_new_repositories flags were all false so every new repo inherited zero hardening. Supply-chain risk for the macdoc-chain (12 downstream Swift deps consumed via ~/bin/macdoc) was material — a single compromised dep could pollute end-user binaries.

Root Cause

Free-tier PsychQuant org with no org-level default enforcement, and explicit per-repo enablement never happened during the rapid package-extraction phase (#78 / #79). The org-level toggles turned out to be policy intent rather than true auto-enablement on free tier — new repos still require explicit per-repo PATCH, which no one was doing during extractions.

Solution

Spectra change psychquant-security-defaults implemented a 4-phase rollout:

1. Org defaults — flipped 5 *_enabled_for_new_repositories flags on PsychQuant org via gh api PATCH /orgs/PsychQuant.
2. macdoc-chain hardening (13 repos: macdoc + 12 downstream Swift deps) — enabled secret scanning + push protection + Dependabot security updates + main branch protection baseline (allow_force_pushes=false, allow_deletions=false, required_linear_history=true, required_approving_review_count=0).
3. Rest of PsychQuant public repos (25 additional: MCP tools + apps + research) — same baseline; private repos (14) got Dependabot alerts only (branch protection & GHAS not available on free tier for private repos).
4. Institutionalisation — macdoc/SECURITY.md as single canonical vulnerability-reporting contract, macdoc/scripts/audit-security.sh as idempotent drift auditor, release-flow gate added to common-release-flow.md requiring new Swift packages to pass audit before first v0.1.0 tag.

Explicit non-goals (per /spectra-discuss): no org-wide 2FA requirement (5-person solo-led org friction > marginal benefit), no GHAS license purchase (~$245/mo for marginal private-repo coverage), no per-repo SECURITY.md copies (single canonical file avoids drift).

Verification

• ./scripts/audit-security.sh exit 0: 52/52 repos meet baseline.
  • 39 public: full baseline (secret scan + push protection + alerts + sec updates + branch protection) all enabled.
  • 14 private: Dependabot alerts enabled; branch protection column reports N/A(tier) per free-tier constraint.
• markdown-swift 48-hour Dependabot smoke: 0 auto-PRs opened, confirming dep tree has no open CVEs and bulk rollout was safe.
• Smoke-test repo (PsychQuant/security-defaults-smoke, created + deleted): confirmed org defaults do not auto-propagate to newly-created repos on free tier — led to spec scenario revision and underlines the release-flow gate's importance.
• Spectra archive: openspec/changes/archive/2026-04-21-psychquant-security-defaults/ with new capability spec repository-security-baseline (8 ADDED requirements applied to openspec/specs/).

Changes

No Git commits yet reference #80. Working-tree changes awaiting commit in macdoc:

• New file macdoc/SECURITY.md (canonical vulnerability reporting contract).
• New file macdoc/scripts/audit-security.sh (drift detector, idempotent, supports --list + single-repo modes).
• New files macdoc/scripts/_phase2-targets.txt, _phase3-public.txt, _phase3-private.txt (declarative target lists).
• New files macdoc/openspec/changes/archive/2026-04-21-psychquant-security-defaults/** + macdoc/openspec/specs/repository-security-baseline/spec.md.
• Modified ~/Developer/che-claude-config/rules/common-release-flow.md (added "Pre-release security audit gate" section).

External effects (config-only, no Git commits):

• PsychQuant org: 5 *_enabled_for_new_repositories + dependency_graph flags flipped to true.
• 39 public PsychQuant repos: security_and_analysis.secret_scanning, secret_scanning_push_protection, automated-security-fixes, and branches/main/protection baseline all enabled.
• 14 private PsychQuant repos: vulnerability-alerts enabled (Dependabot alerts).

Key Findings Surfaced During Apply

1. Free-tier org defaults don't auto-propagate — discovered via smoke-test repo (features stayed disabled on a new public repo even with org flags true). Spec scenario "New repository inherits defaults within 5 minutes" revised to "can be hardened without per-repo configuration change via the release-flow audit gate"; the gate in common-release-flow.md is therefore load-bearing, not optional.
2. Branch protection requires GitHub Pro for private repos — separate paid tier from GHAS. Spec Requirement "Private repositories receive free-tier hardening" revised to explicitly exclude branch protection for private repos; SECURITY.md "Private-repo policy" expanded to document that force-push on private main is not blocked at the GitHub level on free tier.
3. jq // fallback treats false as falsy — caught during Phase 2 verification when all repos showed "force-push=MISSING" despite being correctly false. audit-security.sh switched from // fallback to has("key") guard pattern.

Process Note

This issue used Refs #80 semantics (no Closes trailer anti-pattern like PR #89 on #79) so /idd-close retained gate-check control. Diagnosis comment's Strategy checklist was updated via direct PATCH to reflect actual outcomes ([x] done, [-] won't-fix with reason, [~] partial with reason) before closing — audit trail preserved without bypassing the Checklist Gate.

Follow-ups (not blocking close)

• Commit the working-tree changes (macdoc/SECURITY.md, scripts/audit-security.sh, target lists, archived Spectra change, openspec/specs/repository-security-baseline/spec.md, modified common-release-flow.md) so the closing summary's "Changes" section can reference real commit hashes rather than "none yet".
• If the org ever upgrades to GitHub Pro, enable branch protection on the 14 private repos (tracked implicitly in the [~] marker on private-repo line of the diagnosis Strategy).
• Maintainer-cadence drift check: run ./scripts/audit-security.sh monthly or before every new-package release.