The audit checks that a declared file exists, not that content sits in the file the section model assigns it

[ptr727]

The audit found a missing OPERATIONS.md on ptr727/PhotoCleaner and reported it as a file-presence letter. It did not find that most of the content that file should hold already existed, in .github/copilot-instructions.md. The absent file was the symptom. The misplacement was the cause, and nothing in the audit can see that class.

Raised per AUDIT.md section 9, since it is a spec question rather than a defect in one repo.

What the audit missed

ptr727/PhotoCleaner's .github/copilot-instructions.md carries 311 lines under nine repository-specific level-two headings, on top of the three sections the fleet declares for that file:

## Project Overview
## Architecture & Data Flow          -> ARCHITECTURE.md per spec/section-model.md
## Key Patterns & Conventions        -> ARCHITECTURE.md
## Development Workflow              -> OPERATIONS.md
## Critical Implementation Details   -> ARCHITECTURE.md
## File Processing Extensions        -> ARCHITECTURE.md
## Command Line Usage                -> OPERATIONS.md
## JSON Source Generation            -> ARCHITECTURE.md
## Testing Strategy                  -> ARCHITECTURE.md

spec/section-model.md assigns these destinations explicitly: ARCHITECTURE.md takes "how a code repo is built, its module layout, data flow, and design decisions", and OPERATIONS.md takes "how a repo is run".

The audit reported none of it, because spec/audit.py checks file presence, declared-section presence within a carried file, verbatim content hashes, and workflow interface conformance. A file holding sections that belong to a different declared destination is not any of those.

It is now a duplication rather than only a misplacement

OPERATIONS.md landed on that repo in ptr727/PhotoCleaner#37, and the 311 lines stayed where they were. Both files now describe overlapping ground, Development Workflow against Runbooks being the clearest case, and neither points at the other. That is the state the destinations exist to prevent, and it was reached by an audit reporting clean on the half it can see.

Worth noting how the report was written: the new OPERATIONS.md was authored fresh, against the code, without reconciling it against the description already sitting in copilot-instructions.md. An audit that had flagged the overlap would have made that a migration rather than a second draft.

What a check might do, and why the obvious version is wrong

The shape that fits the existing engine is structural rather than semantic. For a carried file with fidelity: intent, collect its level-two headings, subtract the ones files.json declares for it, and compare the remainder against the headings other destinations declare. A match is a drift finding naming both files.

The tempting version, comparing content for similarity, is explicitly rejected by spec/section-model.md:

A word-overlap or similarity heuristic does not: a repo-specific rule written in ordinary governance vocabulary scores as a reworded duplicate of a rule it has nothing to do with, so the cheap check is confidently wrong in exactly the direction that loses content.

That warning is about migration rather than detection, but it applies here for the same reason, and a detector built on similarity would produce findings whose remedy is to delete content.

Open questions

1. Should an undeclared level-two heading in an intent file be a finding at all? A repo is allowed local additions, and section-model.md says a local addition is promoted or moved rather than dropped. The finding would be "this belongs elsewhere", not "this should not exist", and the two read differently to whoever picks it up.
2. Is the destination mapping declarable? Today section-model.md states it in prose. A check needs it as data, which means a heading-to-destination table in spec/, and that table is a maintenance surface of its own.
3. Does this reach ARCHITECTURE.md, which is declared but advisory? Flagging content that belongs in a file the repo is not required to have needs a stated answer.
4. How many repos does this affect? PhotoCleaner is the one repository looked at closely. The pre-split AGENTS.md shape that produced it was fleet-wide, so the honest expectation is that it is not alone, and that number should be measured before a check is designed rather than after it starts reporting.

[ptr727]

Re-measured against develop @ 2951273. The weaker half landed; the ask in this issue did not. Trimming so the residue is legible.

Now exists — spec/audit.py:743-755 emits an undeclared-section advisory:

section: '<h2>' in <path> is not a declared section - reconcile it (a duplicate of a verbatim section, or repo-specific content that moves to a topical doc), or confirm it is intentional (spec/section-model.md)

It collects the file's ## headings, subtracts what spec/files.json declares, and reports the remainder as DRIFT. Scoped to AGENTS.md and GOVERNANCE.md (the two files section-model.md governs) and skipped on the hub itself, whose copies are the source. That is steps one and two of the three-step shape this issue proposed, and it answers open question 1 in the affirmative: an undeclared H2 is a finding, at advisory weight.

Still missing — the third step, which is the part with the diagnostic value. The check says "this heading is undeclared"; it does not compare the remainder against the headings other destinations declare, so it cannot say "this belongs in OPERATIONS.md". On the PhotoCleaner case that found this, the advisory would flag nine headings inside .github/copilot-instructions.md — except that file is out of scope, so it flags nothing at all, and the missing-OPERATIONS.md letter still reports the symptom while the misplacement stays invisible.

Open questions, restated:

1. Should an undeclared H2 be a finding at all — answered by the implementation: yes, advisory.
2. Is the heading-to-destination mapping declarable as data in spec/, rather than prose in section-model.md? Unanswered, and it is the prerequisite for step three.
3. Does it reach the advisory ARCHITECTURE.md? Unanswered.
4. How many repos are affected? Still unmeasured, and section-model.md's own standard is that this is measured before the check is designed.

Also still true: OPERATIONS.md and .github/copilot-instructions.md on PhotoCleaner duplicate each other (Development Workflow vs Runbooks) with neither pointing at the other. The advisory does not see it, because copilot-instructions.md is outside the two-file scope.

Retitling suggestion: "The undeclared-heading advisory says a heading is undeclared, not where it belongs".