docs(golden): authoring guide for new and existing cases

Author: bnusunny

tests/golden/README.md

@@ -0,0 +1,65 @@
+# Golden Templates
+
+Pinned outputs of `sam build` and `sam package` for representative templates.
+Catches output-shape regressions in SAM-CLI's local pipeline. See
+[`designs/golden-templates-and-semver-check.md`](../../designs/golden-templates-and-semver-check.md)
+for the full design.
+
+## Layout
+
+```
+tests/golden/
+├── templates/
+│   ├── sam_resources/<case>/         # AWS::Serverless::* coverage
+│   ├── packageable_resources/<case>/ # Raw CFN resource coverage
+│   ├── language_extensions/<case>/   # Fn::ForEach et al
+│   └── cross_cutting/<case>/         # Nested stacks, AWS::Include, etc.
+└── ... (harness code)
+```
+
+Each case directory contains:
+- `template.yaml` — the input template.
+- `metadata.yaml` — `language_extensions: bool`, `description`, `issue_refs`.
+- `src/` — any source files referenced by `CodeUri` etc.
+- `expected.build.yaml` — pinned post-build template (regenerated by harness).
+- `expected.package.yaml` — pinned post-package template.
+- `README.md` — what this case covers and why it's pinned.
+
+## Adding a new case
+
+1. Create the case directory and author `template.yaml`, `metadata.yaml`, `src/`, `README.md`.
+2. Generate the pinned outputs:
+   ```
+   python tests/golden/update_goldens.py --new --filter '<axis>/<case-name>'
+   ```
+3. Eyeball `expected.{build,package}.yaml`. Confirm the shape is what you expect.
+4. Commit everything together.
+
+The semver gate treats new cases as additions and does not require a version bump.
+
+## Re-pinning an existing case
+
+If a SAM-CLI behavior change intentionally alters the expanded output:
+
+```
+python tests/golden/update_goldens.py --filter '<axis>/<case-name>'
+```
+
+Review the diff in your IDE before committing. **Modifying or deleting an
+existing pin requires a major version bump in `samcli/__init__.py` in the
+same PR**, enforced by `.github/workflows/golden-semver-gate.yml`.
+
+## Inspecting differences
+
+```
+python tests/golden/update_goldens.py --diff --filter '<glob>'   # show would-be changes
+python tests/golden/update_goldens.py --check                    # exit 1 if anything would change
+```
+
+## Running the suite
+
+```
+pytest tests/golden                                              # all cases
+pytest tests/golden -k foreach_static                            # one case
+make test-all                                                    # part of make pr
+```