Skip to content

spec/files.json doesn't declare copilot-instructions.md's 'When in Doubt' section, so every carrying repo gets a phantom drift finding #989

Description

@ptr727

What happened

spec/files.json's entry for .github/copilot-instructions.md declares:

{
  "path": ".github/copilot-instructions.md",
  "fidelity": "intent",
  "whole": true,
  "sections": [
    "Commit Messages and Pull Request Titles",
    "Reviewing Carried Fleet Content",
    "GitHub Copilot Review Runbook"
  ],
  "placeholders": ["<owner>", "<repo>", "<N>"],
  "appliesTo": "*"
}

But the hub's own canonical .github/copilot-instructions.md carries a fourth heading, ## When in Doubt, right after the "Disproved Claims" ledger:

## When in Doubt

Stop and report the uncertainty. Do not guess at an instruction, suppress a possible finding, or
claim coverage that the review did not perform.

Since this heading isn't in the declared sections list, spec/audit.py's undeclared-section advisory (per spec/section-model.md's "The undeclared-heading advisory also runs against .github/copilot-instructions.md") flags it on every repo that carries the file verbatim -- there's no local addition to reconcile, it's the hub's own content the manifest just doesn't know about.

Where I hit it

ptr727/HomeAutomation-Config's resync (#75/#76): re-vendored copilot-instructions.md from the hub (minus the hub's own Disproved Claims ledger entries, per the carried-instruction-file-guard), which correctly carries "When in Doubt" too. spec/audit.py now reports:

DRIFT  section: 'when in doubt' in .github/copilot-instructions.md 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)

...against content that's genuinely hub-canonical, not repo-specific. This will recur for every other fleet repo the next time it resyncs copilot-instructions.md to current main.

Suggested fix

Add "When in Doubt" to the sections array in spec/files.json for this file.

audit run 2026-08-25T13:46:24Z | hub fa63163

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions