Key OPERATIONS.md to the need for it, not to the workflow model

[ptr727]

Closes the OPERATIONS.md half of the topical-destination question Pieter raised, and states the rule that decides what earns a declared destination at all.

The defect

OPERATIONS.md was declared appliesTo: ["operational"], which binds a content need to a workflow model. Those are unrelated axes. operational describes where config lives and how a change reaches develop. It says nothing about whether the repo has runbooks, so the selector read a sufficient condition as a necessary one.

Blog is the proof. It was reclassified from operational to release today and its runbook needs did not change by one word: same host, same deploy, same staging, same rsync. Only the commit-flow classification moved. A doc requirement that appears and disappears on an unrelated axis is mis-keyed.

The existing rationale already generalized.spec/section-model.md justified mandating the file like this:

the convention was already emerging unevenly: of the four operational repos, two wrote one unprompted and the others scattered the same material across ad-hoc names

Nothing there depends on the workflow model. Every repo has operational surface: publishing to a package registry needs trusted-publisher setup, shipping an image needs registry credentials, serving a site needs a deploy path and a staging story.

The change

• OPERATIONS.md is appliesTo: "*", required everywhere, still presence-checked only, so its content stays entirely the repo's own.
• A repo with nothing to say carries a stub of the headings, not a blank file. Same cost, strictly more useful: a stub names the destination and its shape, where a blank names only the destination.
• Both spec/section-model.md and STANDUP.md now say explicitly that the workflow model and this file are unrelated, so nobody re-derives the link.

The rule this also states

A destination is declared when its content class recurs across repos.

• Software architecture recurs, because every code repo has one, so ARCHITECTURE.md stays declared, and advisory, because how much of it earns a separate document is contextual.
• A home-device inventory (ESPHome-Config's devices.md) does not recur, so it stays the repo's own file, neither declared nor mandated.

The scattering these destinations prevent is the same material landing under different names in different repos. That has no force for content existing in exactly one repo, and declaring a destination for a one-repo need would grow the list without bound while still lagging whatever the next repo invents.

This also dissolves an asymmetry that had been accidental rather than decided: OPERATIONS.md mandatory and ARCHITECTURE.md advisory are consistent once declared and required are separate questions. Both are declared. Only the universal one is required.

The hub now complies with its own rule

ProjectTemplate carried no OPERATIONS.md, so this PR would have shipped a rule the hub itself broke.

It now has a real one, not a stub, covering what this repo has actually hit: running the gates the way CI runs them (including that a bare prose_lint.py runs DEFAULT_RULES and under-reports), the fleet audit, the configure.sh runbook with its blast radius stated, branch recovery via git push origin <sha>:refs/heads/<branch>, and the two live gh limitations on this host.

Fleet impact, stated rather than discovered

This makes the file required for 18 more repos. Measured live:

	Count	Repos
Have it	3	ESPHome-Config, Financial-Modeling, HomeAssistant-Config
Missing	18	the rest, including ProjectTemplate

This PR fixes the hub, leaving 17 repos that will report a new LETTER file: OPERATIONS.md absent finding on the next audit. That is the intended consequence of widening the requirement, not a surprise, and a stub satisfies it. It is worth knowing before the next fleet audit reads noisier than the last one.

Verification

python3 scripts/test_prose_lint.py 144 tests, OK
python3 scripts/test_repo_gate.py 23 tests, OK
python3 scripts/test_pr_review.py 27 tests, OK
python3 spec/audit.py --selftest SELFTEST PASS
python3 scripts/repo_gate.py eol 0, sha-pin 0
python3 spec/validate.py OK, 21 cataloged
prose_lint --check charset --check dupword --check spelling clean
prose_lint --diff HEAD (dash, semicolon, comment rules, charset, dupword, spelling) clean
markdownlint-cli2 (docker, the three docs) 0 issues

cspell was run and reports words in OPERATIONS.md and pre-existing ones in STANDUP.md. None are gated: the CI cspell step covers README.md and HISTORY.md only, deliberately, because gating all markdown would mean endlessly padding cspell.json with technical terms. Nothing was added to the dictionary.

Not in this PR

The advisory audit dimension for misplaced content in undeclared markdown, which is the other half of the discussion. It needs spec/audit.py to enumerate unmatched markdown and AUDIT.md to carry the agent's classification step, and it is cleaner as its own change.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the fleet documentation model so OPERATIONS.md is required based on the recurring need for operational/runbook content rather than being keyed to the operational workflow model, and adds an OPERATIONS.md to ProjectTemplate so the hub complies with the baseline it defines.

Changes:

• Make OPERATIONS.md universally required by changing spec/files.json from appliesTo: ["operational"] to appliesTo: "*".
• Update spec/section-model.md and STANDUP.md to explicitly state that workflow model and operational documentation needs are orthogonal, and document the “declared destination” rule.
• Add a new OPERATIONS.md runbook for this repository and update TODO.md to track a related STANDUP improvement.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
TODO.md	Replaces the prior STANDUP-related backlog item with a more explicit branch-bootstrap step proposal.
STANDUP.md	Updates onboarding guidance to reflect OPERATIONS.md being required for all repos and clarifies the workflow-model independence.
spec/section-model.md	Updates the destination/requirement rationale for OPERATIONS.md and documents the rule for when destinations are declared.
spec/files.json	Makes OPERATIONS.md a universal baseline requirement (appliesTo: "*") instead of workflow-model-scoped.
OPERATIONS.md	Adds an operations/runbook document for ProjectTemplate covering gates, audit, repo-config application, and related tooling notes.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (2)

OPERATIONS.md:20

• The editorconfig-checker command here doesn’t match the CI invocation in .github/workflows/validate-task.yml (missing --workdir /check and adding an extra ec argument). Since this section is explicitly “Run the gates the way CI runs them”, it should mirror the workflow command exactly to avoid local runs behaving differently.

docker run --rm --pull=always -v "$PWD:/check" mstruebing/editorconfig-checker:latest ec

spec/section-model.md:66

• This section says “Three topical docs take it” but the destination list omits TODO.md (which STANDUP.md includes as a declared destination for repo-specific backlog content). This inconsistency can lead to agents scattering TODO/backlog content under other filenames.

A repo's own content is not carried and is not declared here, so extraction needs a predictable destination rather than a judgment call per repo. Three topical docs take it, chosen by what the content *is*:
- [`CODESTYLE.md`][codestyle]: a repo's language and formatting conventions beyond the carried rules.
- `ARCHITECTURE.md`: how a code repo is built, its module layout, data flow, and design decisions.
- `OPERATIONS.md`: how a repo is run, covering runbooks, backup, log and debug procedures, tool-usage notes, and config layout. It is the operational analogue of `ARCHITECTURE.md`, and it is where an `AGENTS.md` split puts the repo-specific half.

[ptr727]

Closing the loop on the two suppressed findings, both verified before accepting and both fixed in f449da8.

1. The editorconfig-checker line did not match CI. Real, and it mattered in that section.

CI runs:

docker run --rm --pull=always -v "$PWD":/check --workdir /check mstruebing/editorconfig-checker:latest

I had written -v "$PWD:/check" with a trailing ec and no --workdir. In a section titled "Run the gates the way CI runs them", that is exactly the drift the section exists to prevent, so it now mirrors CI byte for byte.

I checked whether my form was actually broken rather than assuming either way, by dropping a deliberate LF violation into the tree and running both:

mine: ec-probe.md: Not all lines have the correct end of line character -> 1 errors found
CI's: ec-probe.md: Not all lines have the correct end of line character -> 1 errors found

Identical. The image's default working directory is already /check and ec is its default command, so my form was not vacuous and the earlier local pass was real. The fix removes a dependency on those image defaults rather than repairing a broken command, which is worth stating precisely so the change is not read as a bigger correction than it is.

2. "Three topical docs" against STANDUP.md's four. Real, and section-model.md was the wrong one.

STANDUP.md listed four including TODO.md, spec/section-model.md listed three and omitted it. A reader of the spec therefore had no declared destination for backlog content, which is precisely the scattering that section exists to prevent. section-model.md now lists four.

Both of these were pre-existing in one half and introduced by me in the other, so I have not tried to separate blame. They are fixed where they sit.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (1)

spec/section-model.md:73

• This PR updates the rule so OPERATIONS.md is required for every repo, but reports/conformance-matrix.md still states the old behavior (it says OPERATIONS.md is required only for workflowModel: operational with appliesTo: ["operational"]). That leaves the hub docs internally inconsistent and can mislead readers using the conformance matrix.

Please update the conformance-matrix row (currently reports/conformance-matrix.md:22) to reflect the new appliesTo: "*" requirement (and any similar references, if added later).

**`OPERATIONS.md` is required for every repo**, declared in [`files.json`][files] as `appliesTo: "*"` and checked for presence only, the same footing as `README.md` and `HISTORY.md`, so its content is entirely the repo's own. It is mandatory rather than advisory because the convention was already emerging unevenly: of the four operational-model repos, two wrote one unprompted and the others scattered the same material across ad-hoc names, which is the improvisation these destinations exist to prevent. That reasoning never depended on the workflow model. Every repo has operational surface, since publishing to a package registry needs trusted-publisher setup, shipping an image needs registry credentials, and serving a site needs a deploy path and a staging story. A repo with nothing to say still carries the file as a stub, meaning those five headings with no content under them, because a stub names the destination and its shape where a blank file names only the destination. This repo's own [`OPERATIONS.md`][operations] is the worked example.
**The workflow model and the need for this file are unrelated axes.** `operational` as a `workflowModel` describes where config lives and how a change reaches `develop`, not whether the repo has runbooks. Keying the file to that selector read a sufficient condition as a necessary one, since an operational-model repo certainly has runbooks while a release repo has them too. Reclassifying a repo between models does not change how much operational surface it has, which is the test that showed the selector was wrong.
**A destination is declared when its content class recurs across repos.** Software architecture recurs, because every code repo has one, so `ARCHITECTURE.md` is declared. A home-device inventory does not recur, so it stays the repo's own file, neither declared nor mandated. The scattering these destinations prevent is the same material landing under different names in different repos, and that has no force for content existing in exactly one repo. Declaring a destination for a one-repo need would grow this list without bound and still lag whatever the next repo invents.

[ptr727]

Third round's suppressed finding was real and is fixed in 5343e1a. Verified before accepting, as always with a suppressed one.

reports/conformance-matrix.md:22 still read:

Carries a required OPERATIONS.md (appliesTo: ["operational"], presence-checked) for its runbooks.

This PR makes that false. Merging without the fix would have shipped the hub contradicting itself in the document an agent reads to learn what a shape requires, which is worse than the original defect.

The operational row now states what actually distinguishes that shape: its develop ruleset carries no pull_request rule, so branch discipline rests on the instruction rather than the gate.

Checking that row also caught something Copilot did not flag. It still claimed Blog as the next operational standup, and Blog moved to release plus source-only earlier today. Blog now has its own row rather than sitting under a model it no longer uses.

One deliberate cost: the new row adds a single warn-only dash finding, the | - | empty cell that every other row in the table also carries. The rule reads a table placeholder as prose. Writing my row differently to satisfy a warn-only rule would make the table inconsistent for no gain, so the row keeps the table's convention and the rule gap is a follow-up. That is the same judgment applied in #503, where a command comment got a label because relabeling improved it, and in #500, where a URI got an exemption because no edit could fix it.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (2)

OPERATIONS.md:25

• This says the second prose invocation is "warn-only", but the command shown here will still exit non-zero locally on findings. In CI it’s warn-only because the workflow runs this step with continue-on-error: true (see .github/workflows/validate-task.yml:76-78). Clarifying that distinction will avoid readers treating a failing local run as unexpected.

The first prose invocation gates. The second is warn-only and reports the backlog that is corrected as each file is next edited.

OPERATIONS.md:82

• These Docker commands differ from the documented canonical invocations (missing --workdir /workdir and running cspell over all **/*.md). As written, they may not run from the mounted directory, and they don’t mirror CI’s cspell scope (README.md + HISTORY.md only). Aligning with GOVERNANCE.md:338-345 keeps the runbook consistent and avoids extra non-gated spelling noise.

docker run --rm --pull=always -v "$PWD:/workdir" davidanson/markdownlint-cli2:latest "**/*.md"
docker run --rm --pull=always -v "$PWD:/workdir" ghcr.io/streetsidesoftware/cspell:latest --no-progress "**/*.md"

[ptr727]

Fourth round's two suppressed findings, both real, both fixed in b7e42a2.

1. "Warn-only" attributed the leniency to the wrong thing. The command exits non-zero locally whenever findings exist. It is warn-only in CI because the step sets continue-on-error: true, verified at .github/workflows/validate-task.yml:77. A reader following the runbook would have read the expected result as a failure. The file now says where the leniency comes from.

2. The Docker lines had drifted from the canonical invocations. Checked against GOVERNANCE.md:338-345: both omitted --workdir /workdir, and cspell read **/*.md where the canonical form reads README.md HISTORY.md. Both now match byte for byte.

The cspell scope is the more useful half of that. Reading every markdown file is not just non-canonical, it produces findings no gate acts on, since the CI cspell step covers those two files only. So the file now carries the reason as well as the command, because a reader who does not know why the scope is narrow will widen it back and generate noise. That reason is the same one the workflow comment gives: gating every markdown file would mean padding cspell.json with technical terms without end, and broad live spell-check is the editor extension's job.

This is the third round to find real problems in OPERATIONS.md. It was a large amount of new prose written quickly, and a runbook that misdescribes its own tooling is worse than no runbook, so the rounds have been earning their place rather than polishing.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (1)

OPERATIONS.md:33

• prose_lint.py can be invoked on an explicit file path (even if untracked), so saying it "reads only files git tracks" is only accurate for whole-tree discovery modes (e.g., prose_lint.py . / --diff). As written, this can mislead a reader into thinking an untracked file can never be checked locally.

`prose_lint.py` reads only files git tracks, so a new file reports clean until it is staged. The first clean run on an unstaged file is vacuous.

[ptr727]

Fifth round's suppressed finding, real, fixed in b0e0732. Verified empirically rather than by reading the code, since the claim was about behavior:

$ printf 'The the duplicated word here.\n' > untracked-probe.md # untracked
$ python3 scripts/prose_lint.py untracked-probe.md --check dupword
untracked-probe.md:1: dupword: duplicated word 'The' -> exit 1
$ python3 scripts/prose_lint.py . --check dupword
(untracked-probe.md not seen)

Exactly as you said. discover() short-circuits on p.is_file() before consulting git ls-files, so an explicit path is always read. The tracked-files limit applies to whole-tree discovery and --diff only.

This one mattered more than an ordinary inaccuracy. As written it told a reader that a new file cannot be checked before staging, which discourages the single habit that catches a new file's problems before CI does. This PR is the worked example: OPERATIONS.md was created with LF against a CRLF-default repo and failed the first CI run. Advice that steers someone away from checking a new file locally is advice that reproduces that failure.

The line now separates the two modes and says to name a new file directly.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (3)

OPERATIONS.md:33

• Same issue later in this section: prose_lint.py . isn’t a valid path/command in this repo; the actual script is scripts/prose_lint.py. This affects copy-pasteability of the guidance.

Whole-tree discovery reads only files git tracks, so `prose_lint.py .` and `--diff` do not see a new file until it is staged, and a clean whole-tree run proves nothing about an unstaged one. An explicit path is always read, tracked or not, so name a new file directly to check it before staging.

OPERATIONS.md:9

• OPERATIONS.md refers to running prose_lint.py <file>, but the script in this repo is scripts/prose_lint.py (there is no top-level prose_lint.py). As written, the command name is misleading and may not work for readers.

This issue also appears on line 33 of the same file.

CI passes explicit `--check` lists, and a bare `prose_lint.py <file>` runs `DEFAULT_RULES`, which omits `comment-wrap`, `comment-case` and `sentence-split`. A bare run therefore under-reports and a clean result from it proves less than it appears to. Run the CI invocations:

spec/section-model.md:62

• This sentence says repo-specific content “is not declared here”, but this very section immediately declares the standard destinations (CODESTYLE.md, ARCHITECTURE.md, OPERATIONS.md, TODO.md). Dropping that clause would avoid a self-contradiction for downstream readers.

A repo's own content is not carried and is not declared here, so extraction needs a predictable destination rather than a judgment call per repo. Four topical docs take it, chosen by what the content *is*:

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (2)

OPERATIONS.md:19

• The JSON validity loop doesn’t include repo-config/operational/develop.json, so it misses one of the repo-config JSON files that CI carries and validates elsewhere.

for f in registry/*.json spec/*.json repo-config/*.json; do jq empty "$f"; done

OPERATIONS.md:9

• OPERATIONS.md says a bare prose_lint.py run under-reports because DEFAULT_RULES omits sentence-split, but CI also doesn’t run sentence-split (see .github/workflows/validate-task.yml). As written, this implies CI checks sentence-split when it doesn’t, which is misleading.

CI passes explicit `--check` lists, and a bare `python3 scripts/prose_lint.py <file>` runs `DEFAULT_RULES`, which omits `comment-wrap`, `comment-case` and `sentence-split`. A bare run therefore under-reports and a clean result from it proves less than it appears to. Run the CI invocations:

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.