Skip to content

Make the runbook's commands paste-safe - #518

Merged
ptr727 merged 1 commit into
developfrom
fix/operations-paste-safe-placeholders
Aug 1, 2026
Merged

Make the runbook's commands paste-safe#518
ptr727 merged 1 commit into
developfrom
fix/operations-paste-safe-placeholders

Conversation

@ptr727

Copy link
Copy Markdown
Owner

Fixes the two placeholder findings Copilot raised on the promotion #517, plus the six more of the same class.

This has to land on develop first: #517's head isdevelop, and develop carries a pull_request rule, so the promotion cannot be fixed in place.

The defect

OPERATIONS.md wrote shell placeholders as <owner>/<repo>. A POSIX shell parses < as input redirection, so pasting one is a syntax error, in a file whose entire purpose is being pasted:

$ repo-config/configure.sh check <owner>/<repo>
bash: syntax error near unexpected token `newline'

The bracket form pastes cleanly, and STANDUP.md already writes the same command that way:

repo-config/configure.sh check [owner/repo] [release|operational]

So the runbook was both unpastable and the odd one out against the repo's own convention.

Scope: eight, not two

Copilot reported two, one inline and one suppressed. Looking for the whole class found eight across six shell blocks: the prose_lint.py invocation, both configure.sh lines, the branch-recovery git push, both gh run examples, the gh api base-retarget, and two spec/audit.py calls.

Verified by parsing, not by eye

Every sh block was run through bash -n:

6 sh blocks, 0 with syntax errors

That check earned its place. A first pass grepping <[a-z|-]*> reported zero remaining and the parse test still failed block 3, because <RepoName> is uppercase and the pattern was lowercase-only. Checking the property directly caught what checking a proxy for it missed.

Verification

bash -n over every sh block 6 blocks, 0 errors
grep -cE '<[A-Za-z|_-]+>' OPERATIONS.md 0
editorconfig-checker (docker, canonical) clean
markdownlint-cli2 (docker, canonical) 0 issues
prose_lint OPERATIONS.md (charset, dupword, spelling, charset-unknown, dash, semicolon, sentence-split) clean

Once this merges, #517 picks it up automatically, since its head is develop.

🤖 Generated with Claude Code

OPERATIONS.md used <owner>/<repo> style placeholders inside shell snippets. A
POSIX shell parses < as input redirection, so pasting one is a syntax error,
in a file whose entire purpose is being pasted:
$ repo-config/configure.sh check <owner>/<repo>
bash: syntax error near unexpected token `newline'
STANDUP.md already writes the same command as [owner/repo]
[release|operational], so the runbook was also the odd one out.
All eight placeholders across six shell blocks now use the bracket form, and
every block was verified to parse with bash -n rather than by eye. That check
caught <RepoName>, which a lowercase-only grep had missed.
Two of the eight were reported by Copilot on #517, one as an inline comment
and one suppressed. The other six were found by looking for the whole class.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings August 1, 2026 19:20

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates OPERATIONS.md runbook examples to use paste-safe placeholder syntax (square brackets) instead of HTML-escaped angle brackets, so copied commands no longer trigger shell redirection parsing errors. This aligns the operations runbook with the repository’s existing placeholder convention and supports the develop-first promotion workflow described in the PR metadata.

Changes:

  • Replaced &lt;...&gt; / <...> placeholders with [...] across runbook command examples (prose lint, audit, configure, branch recovery, gh run, and gh api).
  • Ensured all updated shell snippets remain syntactically valid when pasted.

@ptr727
ptr727 merged commit 69688ec into developAug 1, 2026
7 checks passed
@ptr727
ptr727 deleted the fix/operations-paste-safe-placeholders branch August 1, 2026 20:49
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@ptr727