docs(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. Component-modification order of operations (copilot-instructions.md, skill-update-component)

Canonical sequence: edit comp.toml → azldev comp update -p <name> → commit all working-tree changes (toml + lock + source-side scripts) → azldev comp render -p <name> → amend (rendered spec). The commit between update and render is mandatory so the %changelog / Release: derived from git log match the committed history rather than the synthetic "dirty" working-tree state.

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.

7. Descriptions over comments (copilot-instructions.md rule 1, comp-toml.instructions.md)

Prefer schema-provided fields (description, replace-reason, skip_reason, …) over TOML comments. Every overlay MUST set description, every rationale string MUST be brief (one short line, motivational, no implementation detail). Includes DO / DO-NOT examples for both descriptions and the (rare) cases where a TOML comment is still appropriate.

8. Single-commit PRs (copilot-instructions.md rule 9)

Each PR lands as a single commit per CONTRIBUTING.md — Pull Request Workflow. If intermediate commits exist during development, squash them with git reset --soft $(git merge-base origin/<base> HEAD) && git commit -S -F <msg> (NOT git merge --squash) so commit metadata stays clean and no upstream changes get inverted.

9. Reviewer-facing-only commit/PR descriptions (copilot-instructions.md rule 10)

Commit messages and PR descriptions MUST describe only changes visible in the diff. Investigations, side-observations, or rejected approaches go to internal notes or follow-up issues, with a link back if needed.

10. Fix drift locally, not via CI patch artifacts (copilot-instructions.md rule 11, skill-update-component drift-fix discipline)

When Render + drift check or Update locks + drift check fails and the bot offers a rendered-specs-patch / locks-patch artifact, re-run the relevant azldev command locally and amend with that output — do NOT gh run download the artifact and git apply it.

11. spec-remove-subpackage / spec-remove-section failure modes (skill-fix-overlay)

Two failure modes documented: %define / %global inside the removed body vanishing (tracked in microsoft/azure-linux-dev-tools#203) and stray buildroot files. %if / %endif balancing around the removed section is handled automatically by the engine.

Files

File	Change
.github/copilot-instructions.md	Hygiene-rules expansion (descriptions-over-comments, signing, render order, single-commit, reviewer-facing descriptions, drift-fix discipline).
.github/instructions/comp-toml.instructions.md	replace-upstream pattern, descriptions-over-comments, public-content hygiene, file-organization rules.
.github/skills/skill-modify-source/SKILL.md	New skill — byte-deterministic Source0 repack.
.github/skills/skill-signing-failure-remediation/SKILL.md	New skill — decision tree for signing/scan failures.
.github/skills/skill-fix-overlay/SKILL.md	Refresh spec-remove-subpackage failure-mode list.
.github/skills/skill-update-component/SKILL.md	Commit-order example + drift-fix discipline.
AGENTS.md	Skill-index entries for the two new skills.
base/comps/AGENTS.md	Directory-level restatement of components.toml hygiene rule.

Single GPG-signed commit per CONTRIBUTING.md — Pull Request Workflow.