instructions: document AZL component-modification workflow conventions

[PawelWMS]

This PR captures the conventions developed during a long-running multi-day session of remediating package-signing/scan failures at the component level (no allow-listing). The goal is to make those conventions discoverable to future Copilot sessions and agents, not to introduce new tooling.

What this PR adds

1. replace-upstream source-override pattern (comp-toml.instructions.md)

Documents the single-step pattern for serving a locally-modified upstream tarball under the same filename: one [[components.<name>.source-files]] block with replace-upstream = true and a replace-reason = "..." string. No separate file-remove overlay is needed; azldev's render step emits an audit WARN log naming the override and the from/to SHA-512 pair.

Covers field semantics, the lookaside URL pattern, the requirement that hash and the $hash segment of origin.uri stay in sync, replace-reason style rules, and the file-organization rules (delete inline components.toml entries when moving to a dedicated *.comp.toml; no tombstone comments).

2. skill-modify-source skill

New skill at .github/skills/skill-modify-source/SKILL.md documenting the canonical modify_source.sh pattern. The lookaside URL embeds the SHA-512 of the served file, so the repack must be byte-deterministic. Covers:

• Required tar flags (--sort=name, --owner=0, --group=0, --numeric-owner, --mtime='@<epoch>', --format=gnu, LC_ALL=C).
• Required xz flags (-T 1, -9).
• Mandatory upstream SHA-512 verification before extract.
• Strip-list vs keep-list strategies with list-discipline rules.
• Output reporting contract (path, hash, ready-to-paste blob-upload command).
• Determinism self-test recipe (two runs must produce byte-identical output).
• Anti-patterns to avoid (multi-threaded xz without --block-size, mktemp for output filename, gzip without -n, find -newer, etc.).
• Canonical ~40-line skeleton showing the whole pattern end-to-end.

3. skill-signing-failure-remediation skill

New skill at .github/skills/skill-signing-failure-remediation/SKILL.md documenting the decision tree:

• (a) No reverse dependencies → drop the component outright (separate PR).
• (b) Offending artefact lives in a test-only or otherwise-optional subpackage → use spec-remove-subpackage (or build.without if a clean bcond exists).
• (c) Reverse deps require the component to keep building → strip subtrees from Source0 via the replace-upstream pattern with a modify_source.sh script (see skill-modify-source).

Always run a reverse-dependency scan before choosing (a) or (b).

4. Render/lock cycle ordering (copilot-instructions.md, skill-update-component)

Canonical sequence: edit comp.toml → azldev comp update -p <name> → commit (toml + lock) → azldev comp render -p <name> → amend (rendered spec). Keeps the lock fingerprint, %changelog, and Release: in sync within a single commit. The existing skill-update-component had this pattern; this PR clarifies the commit order explicitly.

5. GPG signing (copilot-instructions.md)

Every commit MUST be GPG-signed. Verify with git log -1 --show-signature.

6. Public-content hygiene (copilot-instructions.md, comp-toml.instructions.md)

Overlay descriptions, replace-reason strings, comp.toml comments, spec files, modify_source.sh echo lines, commit messages, and PR descriptions describe motivations technically and neutrally — no specific internal infrastructure names (signing services, scanner brand names, internal pipeline/tooling names, internal Azure tenants, etc.). Use neutral phrasing.

Files

File	Change
.github/copilot-instructions.md	+3 lines: GPG signing, public-content hygiene, render order rules.
.github/instructions/comp-toml.instructions.md	+69 lines: replace-upstream source-override pattern, public-content hygiene, components.toml file-organization rules.
.github/skills/skill-modify-source/SKILL.md	New skill (~267 lines).
.github/skills/skill-signing-failure-remediation/SKILL.md	New skill (~98 lines).
.github/skills/skill-update-component/SKILL.md	Clarified commit order with a worked example.
AGENTS.md	+2 lines in skill index for the two new skills.
base/comps/AGENTS.md	+4 lines: components.toml hygiene rule restated at directory-level.

Commits

1. instructions(comp-toml): document replace-upstream source override pattern
2. skills: add skill-modify-source for byte-deterministic Source0 repack
3. instructions: clarify render order, GPG signing, public-content hygiene, and signing-failure remediation skill

All commits are GPG-signed.

[Copilot]

Pull request overview

This PR documents Azure Linux component-modification workflow conventions (source overrides, signing/scan remediation, and update/render/commit ordering) to make them discoverable and repeatable for future contributors and Copilot/agent sessions.

Changes:

• Documented the replace-upstream source-override pattern and related hygiene/workflow guidance in component TOML instructions.
• Added two new skills (skill-modify-source, skill-signing-failure-remediation) and expanded troubleshooting guidance in skill-fix-overlay.
• Clarified component update/render commit ordering and added additional repository workflow rules in Copilot instructions.

Reviewed changes

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

Show a summary per file

File	Description
base/comps/AGENTS.md	Adds components.toml hygiene rules and indexes the new skills for component work.
AGENTS.md	Adds the two new skills to the repo-wide skill index.
.github/skills/skill-update-component/SKILL.md	Clarifies the commit/update/render/amend order and adds local drift-fix discipline guidance.
.github/skills/skill-signing-failure-remediation/SKILL.md	New decision-tree skill for remediation paths (drop component/subpackage vs strip Source0).
.github/skills/skill-modify-source/SKILL.md	New skill documenting a deterministic modify_source.sh repack pattern for replace-upstream.
.github/skills/skill-fix-overlay/SKILL.md	Adds guidance on section scoping pitfalls and %if/%endif hazards when removing sections/subpackages.
.github/instructions/comp-toml.instructions.md	Documents replace-upstream, public-content hygiene, file-organization rules, and build-flag override guidance.
.github/copilot-instructions.md	Adds azldev install/update guidance plus commit signing, hygiene, and component-modification ordering rules.

Comments suppressed due to low confidence (2)

.github/skills/skill-signing-failure-remediation/SKILL.md:72

• The reverse-dependency scan guidance mentions base/comps/*/components.toml, but this repo’s component list is base/comps/components.toml (no per-subdir components.toml). Pointing at a nonexistent path makes the checklist harder to follow and can lead to incomplete scans.

- `Requires:` / `BuildRequires:` references in other components' specs or comp.toml overlays.
- Image manifest inclusions (`base/images/**`).
- References in `base/comps/*/components.toml` or any other comp.toml as a dependency.

.github/instructions/comp-toml.instructions.md:164

• The new replace-upstream / replace-reason keys shown here aren’t currently part of the authoritative schema (external/schemas/azldev.schema.json → SourceFileReference, which has additionalProperties: false). That means schema-based validation/IDE tooling will flag this example (and any real usage) as invalid unless the schema is updated or the docs call out the mismatch explicitly.

filename = "examplepkg-1.2.3.tar.xz"
hash = "<sha512 of LOCALLY-MODIFIED tarball>"
hash-type = "SHA512"
replace-upstream = true
replace-reason = "Upstream tarball ships a vendored copy of a third-party library plus a 'tests/network' tree that trip an automated package-signing pipeline's deep scanner. Repacked under the same filename with those subtrees stripped via base/comps/examplepkg/modify_source.sh; the surviving bits are byte-identical to upstream so the build is unaffected."