Skip to content

Close the Thirteen Open Findings on the Include Mechanism From #1378 #1380

Description

@ptr727

The mechanism pull request for #1317, #1378, merged with thirteen introduced findings open, put here by the maintainer's decision after three granted rounds, since the last two recorded passes surfaced only new edges of the mechanism and no regression of a fix. Each is quoted from that pull request's read record. Fix the code items first, the near-miss marker above all, since it is the one that produces the silent hole in a skill the mechanism exists to prevent.

Code, scripts/build_dist.py

  1. A near-miss marker, <!-- include A.md > B --> without the colon, or a marker line with trailing text past the close, matches nothing and is content, so the region is never filled and --check exits 0. Refuse any HTML comment line beginning <!-- include or <!-- /include that fails the marker regex.
  2. heading_body ends a body at a level-one heading, where spec/audit.py and canonical_review.py match only ## and run through one, and the heading regex accepts a tab after the hashes where they do not. The "split alike" claim in two comments holds for level-two headings only. Decide one reading for the three tools.
  3. A marker may sit up to three spaces indented, but the body is written at column 0 and the closing marker keeps its indent, so a region opened inside a list item renders outside it. Either refuse an indented marker or state that the allowance covers the marker, not the region.
  4. _unindented counts spaces only, so a tab-indented code block's doubled blank lines collapse. Narrow, since the Markdown lint keeps hard tabs out of sources.

Prose

  1. scripts/README.md: the exit-2 cause list omits a body leaving a fence open, a region in a file the walk does not visit, and a file that is not UTF-8, which the skill lists.
  2. AGENTS.md's closing paragraph and docs/fleet-map.md say a skill is "hand-authored" at the skills tree without the include-region qualifier scripts/README.md and .agents/skills/README.md carry.
  3. skill-lifecycle > The Pipeline: "a skill file or source that is not UTF-8" exits 2 only for the Markdown files the walk decodes, so a non-UTF-8 references/*.txt or scripts/ file is copied into both distributions and --check exits 0.
  4. skill-lifecycle > The Pipeline: "exit 2 rather than 1" reads as the unrenderable region's code alone, where a symlink anywhere under the skills tree and an unreadable generated file also exit 2.
  5. skill-lifecycle > The Pipeline: a source need not be tracked, so an untracked or ignored file fills the region locally and exits 2 in CI where the file is absent.
  6. skill-lifecycle > The Doc-Packaging Pattern: the "Included content" shape has no exemplar and no doc-side sentence exists in the tree until a per-class pull request lands the first include. Settle it in that pull request.
  7. .github/copilot-instructions.md > Reviewing Carried Fleet Content: "that key" has no antecedent, since the appositive shows the marker text without saying that <path> > <heading> is the key.
  8. Same unit: the nested-region sentence names an inner key no copy shows, because the render drops the source's own markers, so the object it names exists only in the hub's authored tree.
  9. Same unit: "When the pull request changes the file the fix belongs in" can never be true downstream once the fix is placed in a hub file, and the unit leaves undecided whether a pull request touching the local copy of that path qualifies.

Related: #1379 (the doubled include walk in --check), #1317 (the per-class pull requests that will land the first live region).

Activity

  1. ptr727 commented on Sep 5, 2026

    @ptr727
    OwnerAuthor

    Item 1 is fixed in #1382, including the three-dash opener on both markers. One pre-existing edge the diff pass on that pull request found stays open here, as item 14:

    1. An open marker whose close alone carries the three-dash typo, <!-- include: A.md > B --->, is not a near miss, because the start regex accepts it first and captures the key as A.md > B -. It still exits 2, through the heading lookup as "no heading 'B -' in its source", so the hole stays closed, but the refusal points the author at the source document rather than at the marker they mistyped. Anchor the key capture so a trailing dash run is not part of it, or refuse a key ending in a dash.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    scriptA defect in hub tooling

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions