Sprint 153 Automation Follow-up — git Staging Plan Specification + Broken Ref Periodic Lint

Goals

• Bundle-process 2 automation candidates (seed #20 / #21) derived from Sprint 153 retrospective
• Post-detection (Phase B / Seed #21): Automate Sprint 153 Phase G 5-slug 23-occurrence broken ref cases as periodic lint
• Pre-blocking (Phase A / Seed #20): Convert the git mv + sed staging omission incident that recurred twice in Sprint 153 Phase A/E into a plan-stage checklist

Decisions

• Phase B first / Phase A second: Phase A persona cross-ref cites Phase B deliverable (docs/runbook/doc-ref-lint.md) — dependency order exists
• Phase B: New scripts/check-doc-refs.mjs + new quality-docs job — same pattern as existing check-grafana-metrics.mjs / check-regex-robustness.mjs (runRegressionFixtures() self-test + paths filter + exit code 0/1/2)
• Phase A: New RUNBOOK docs/runbook/git-staging-checklist.md + architect.md / scribe.md persona cross-ref — Sprint 153 3 incidents (commit omission / main exposure / stash drop loss) all directly reflected in recovery procedure §3
• Incident-to-RUNBOOK 1:1 mapping principle: Both RUNBOOKs in this sprint register the immediately preceding sprint's incidents as fixtures/cases — fixing regression blocking essence as "concrete cases" rather than "qualitative rules"
• Each phase: independent PR + Squash merge — separate change scope / risk level (Sprint 150/152/153 pattern directly inherited)

Implementation (2 PR squash merge, origin/main 661cd59 → cc26411)

Phase B Detail — Broken Ref Lint

scripts/check-doc-refs.mjs (255 lines):

• git ls-files '*.md' → 159 tracked .md files (after Phase A merge)
• Two extraction rules: (1) markdown link [text](path) (2) bare doc path docs/.../*.md
• Automatic exemption: external URLs (http:// / https:// / mailto: / file:) / anchor-only / template variables / code fences / inline code
• Explicit exemption: line-end <!-- doc-ref-lint: ignore --> directive
• Self-test fixture: Sprint 153 Phase G 5-slug inline verification (docs/runbook-monitoring-log-rules.md / -ci-cd-rules.md / -annotation-dictionary.md / -migration-rules.md / -work-progress-guide.md) — exit 2 self-test fail on detection count mismatch
• Exit codes: 0 (pass) / 1 (broken ref) / 2 (self-test fail)

CI integration (.github/workflows/ci.yml):

• Added docs paths filter to detect-changes (docs/**/*.md, *.md, .claude/commands/**/*.md, blog/content/**/*.mdx, scripts/check-doc-refs.mjs)
• New quality-docs job alongside quality-monitoring — needs: detect-changes, if: docs == 'true'
• Added docs=true to rebuild_all override branch

Immediate detection + resolution:

• sprint-102.md:76, sprint-102.md:85 — user home ~/.claude/projects/.../memory/... absolute path (outside repo, machine-dependent) → exemption directive applied
• sprint-72.md:37 — file:///root/.claude/... scheme → added file: scheme to validateRef() external URL exemption pattern for automatic handling

Phase A Detail — Staging Checklist

docs/runbook/git-staging-checklist.md (142 lines, 7 sections):

• §1 Overview — Sprint 153 Phase A (self-discovered within single PR) / Phase E (main exposure → PR #241 hotfix) 2 incidents directly cited
• §2 Plan-stage checklist — 4 work type classifications (Edit/Write only / git mv only / sed multi-file / combined) × staging command matrix + pre-commit git status --short + git diff --cached --stat verification
• §3 Recovery procedures — 3 incident types (commit omission / main broken link / git stash push -u + drop untracked loss) all Sprint 153 incident 1:1 mapped
• §4 Plan template example — required items for **staging procedure**: section
• §5 Agent responsibility assignment — architect / scribe / conductor / critic
• §6 Operations procedure — local + CI automation future expansion candidate (pre-push hook / PR check)
• §7 History

Persona cross-ref:

• architect.md: Staging checklist mandatory item added alongside monitoring regex checklist (3 lines)
• scribe.md: When planning document moves/renames, cite §2 explicitly + mandatory post-fix broken ref lint (node scripts/check-doc-refs.mjs) — directly linked to Phase B deliverable

Verification

• Phase B PR #244 CI: 29 success / 0 fail / 11 skipped, mergeStateStatus CLEAN ✅
• Phase A PR #245 CI: 28 success / 0 fail / 12 skipped, mergeStateStatus CLEAN ✅
• Local lint: node scripts/check-doc-refs.mjs run after each phase during sprint — 0 broken refs / fixture 5/5 consistently maintained
• Automatic exemption verification: file: scheme addition + 2 sprint-102.md directives processed all 3 detected cases correctly (0 false positives)
• Self-verification of 2 new RUNBOOKs via doc-ref-lint: doc-ref-lint.md / git-staging-checklist.md added during this sprint also passed lint

Branch Discipline

• Both PRs use new branches + Squash merge — 20 consecutive sprints compliant (since Sprint 134 violation)
• 0 direct commits to main

New Patterns

1. Post-detection + pre-blocking pair pattern — Phase B (lint, post-detection) + Phase A (checklist, pre-blocking) matched as pair. Two-stage safety net simultaneously introduced for a single defect domain
2. Direct 1:1 mapping of preceding sprint incidents to fixtures/cases — Phase B self-test 5 slugs (= Phase G slugs 5 types) + Phase A recovery procedures 3 types (= Phase A/E + stash drop secondary incident). Fixing regression blocking essence as "concrete cases" rather than "qualitative rules"
3. New RUNBOOK self-verification via lint — Phase B introduced lint immediately verifies Phase A deliverables too. Meta-self-verification cycle completed
4. SSOT 5-item simultaneous update obligation when adding new paths filter items — (1) filters block (2) outputs (3) rebuild_all branch (4) job needs (5) job if. Phase B in Sprint 154 correctly updated all 5
5. Single sprint 2 PR bundled response — Sprint 152 (3 PR / blog) / Sprint 151 (2 PR / SQL) / Sprint 150 (3 PR / seed bundle) pattern inherited. Impact scope separated + sequential merge

Related Memory

• sprint-window.md