docs(instructions): document AZL component-modification workflow conventions

.github/copilot-instructions.md

@@ -71,6 +71,14 @@ When making a PR, the lock and rendered specs must be updated and self-consisten
 
 Run all commands from the repo root (where `azldev.toml` lives). If the terminal's cwd has drifted, use `azldev -C /path/to/repo <command>`. Use `azldev --help` and `azldev <command> --help` for current syntax — the tool is under active development.
 
+**Installing / updating `azldev`:** the canonical install/update command is
+
+```bash
+go install github.com/microsoft/azure-linux-dev-tools/cmd/azldev@main
+```
+
+`@main` pins to the latest published source — fine for an actively-tracked dev tool. The binary lands at `$(go env GOPATH)/bin/azldev`. Verify with `azldev --version`. Re-run the same command to update; new features (e.g. project-config validation rules) land continuously, so running stale `azldev` against a fresh repo state can produce false-positive CI failures.
+
 **Agent-friendly flags:** Use `-q` (quiet) to reduce noise and `-O json` for machine-parseable output. These are global flags and work on all commands.
 
 | Task | Command |
@@ -97,8 +105,14 @@ Run all commands from the repo root (where `azldev.toml` lives). If the terminal
 
 ## Repository Hygiene Rules
 
-1. **Overlay descriptions**: Every overlay MUST include a `description` field explaining *why* the change is needed.
+1. **Descriptions over comments**: Use the schema-provided fields (`description` on overlays, `replace-reason`, `skip_reason`, etc.) instead of TOML comments. Every overlay MUST set `description`, and every rationale string MUST be brief — one short line, motivational (the *why*), not implementation detail. See [`comp-toml.instructions.md` — Descriptions over comments](instructions/comp-toml.instructions.md#descriptions-over-comments).
 2. **Naming**: Component names should match the upstream package name. Use `upstream-name` when the upstream name differs (e.g., `upstream-name = "redhat-rpm-config"` for `azurelinux-rpm-config`).
 3. **Schema validation**: The authoritative schema is `external/schemas/azldev.schema.json`. Do NOT add `$schema` keys to TOML files — `$` is invalid at the start of a bare TOML key.
 4. **Don't edit generated output**: Build artifacts in `base/out/` and `base/build/` are generated (configured by `output-dir`, `log-dir`, `work-dir` in `base/project.toml`) — never edit them directly. Note: `prep-sources -o <dir>` writes to a user-specified directory, separate from these project output dirs.
 5. **Mandatory testing**: Any change that affects a component's output (overlays, build config, spec edits, version bumps, new components) MUST be validated by building AND testing the resulting RPMs. A successful build alone is not sufficient — smoke-test in a mock chroot. Pure organizational changes (moving definitions between files, editing descriptions/comments) do not require rebuild. See `AGENTS.md` for the full testing protocol.
+6. **Commit signing**: Every commit MUST be GPG-signed (`git commit -S`, or `commit.gpgsign = true` in your git config). Verify with `git log -1 --show-signature` — the output must include a `Good signature` line. Do **not** disable signing (`--no-gpg-sign`) even for fix-branch / amend / force-push workflows; if a commit fails due to a signing-tool issue, surface the error rather than working around it.
+7. **Public-content hygiene**: In committed content — overlay `description`s, `replace-reason` strings, `*.comp.toml` comments, `*.spec` files, `modify_source.sh` echo lines, commit messages, PR descriptions — describe motivations **technically and neutrally**. Do not name specific Microsoft-internal infrastructure (signing services, scanner brand names, internal pipeline names, internal CLI wrappers, internal Azure tenants, etc.). Use neutral phrasing like "automated package-signing pipeline", "FS-aware deep scanner", "automated malware scan". See [`comp-toml.instructions.md` — Public-content hygiene](instructions/comp-toml.instructions.md#public-content-hygiene) for examples.
+8. **Component-modification order of operations**: For any component change, the canonical sequence is `edit comp.toml → azldev comp update -p <name> → commit ALL working-tree changes (comp.toml + lock + anything else like source-side scripts) → azldev comp render -p <name> → amend (rendered spec)`. The **commit between `update` and `render` is mandatory** and must include the entire working tree, not just the lock and comp.toml: `%changelog` / `Release:` are derived from `git log` for the component, and `azldev` treats any uncommitted working-tree change as a synthetic "dirty" commit. Rendering with uncommitted changes therefore produces an extra `Release:` bump and a `Local changes (uncommitted)` changelog entry that diverges from the actual commit — the `Check Rendered Specs` CI check then fails. Commit first; render after; amend the rendered spec into the same single commit. See [`skill-update-component`](skills/skill-update-component/SKILL.md).
+9. **Single-commit PRs**: Per [`CONTRIBUTING.md` — Pull Request Workflow](../CONTRIBUTING.md#pull-request-workflow), each PR should land as a single commit. If you produce intermediate commits during development (e.g., separate the source override from a follow-up simplification), squash them into one GPG-signed commit before opening or marking the PR ready for review. Use `git reset --soft <merge-base>` followed by `git commit -S -F <message>` rather than `--squash` so the commit metadata stays clean. A multi-commit PR will fail the merge bar.
+10. **Reviewer-facing-only commit/PR descriptions**: Commit messages and pull-request descriptions MUST describe **only changes that are visible in the diff** to a reviewer. Do NOT include narrative about investigations, findings, side-observations, or background that did not produce any file changes — that context belongs in the working-session log, internal notes, or a follow-up issue. For example, a commit that strips one file from a tarball must not include a section about an unrelated `gzip: stdin: not in gzip format` warning the author noticed while investigating, because there's no diff for a reviewer to evaluate against it. If an investigation produced a follow-up issue or TODO, link to it from the commit message ("filed as #N for follow-up") — the link itself is the diff-visible artefact. Commit/PR descriptions are reviewer-facing artefacts that explain *what this change does*, not *what the author thought about while writing it*. See [`skill-update-component`](skills/skill-update-component/SKILL.md).
+11. **Fix drift locally, never by downloading CI patch artifacts**: When the `Render + drift check` (or `Update locks + drift check`) PR check fails and posts a comment linking the `rendered-specs-patch` / `locks-patch` artifact, do NOT `gh run download` it and `git apply` the result. Re-run the relevant `azldev` command locally instead (`azldev comp render -p <name>` and/or `azldev comp update -p <name>`), inspect the diff, and amend the commit with the locally-produced output. The CI patch is a convenience for human reviewers eyeballing a small change — using it as an automated fix path skips the local-reproduction step, leaves the workflow non-reproducible from a fresh clone, and masks any environment-skew bug between local `azldev` and the CI container. If local `azldev` does NOT reproduce the CI render, the fix is to update your local toolchain (`go install github.com/microsoft/azure-linux-dev-tools/cmd/azldev@main`) — **not** to bypass it. If they still disagree after that, surface the discrepancy as a bug to investigate rather than papering over it with the patch artifact.