docs: add ADRs for subject format selection

README.md

@@ -82,6 +82,9 @@ If the repository uses a custom `sub` template, a warning is printed: the patter
 default template and will not match. GitHub Enterprise Server has no immutable subjects; use
 `--mutable` there.
 
+Rationale: [ADR 1](docs/adr/0001-immutable-subject-format-by-default.md),
+[ADR 2](docs/adr/0002-repository-setting-overrides-format-flag.md).
+
 ## Releases
 
 Pushing a `v*` tag builds binaries for all platforms via

docs/adr/0001-immutable-subject-format-by-default.md

@@ -0,0 +1,32 @@
+# 1. Immutable subject format by default
+
+Date: 2026-11-06
+
+## Status
+
+Accepted
+
+## Context
+
+GitHub Actions OIDC tokens identify the repository in the `sub` claim. The legacy format
+`repo:OWNER/REPO:…` uses names only. After a rename, transfer or deletion, someone else can
+register the old name and obtain tokens that match existing trust policies.
+
+GitHub introduced [immutable subjects](https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens)
+of the form `repo:OWNER@OWNER_ID/REPO@REPO_ID:…`. Repositories created after 2026-07-15 use it
+by default; older ones keep the legacy format until they opt in. GitHub Enterprise Server does
+not support it.
+
+## Decision
+
+Emit the immutable format by default. The extension resolves owner and repository IDs via the
+API. `--mutable` selects the legacy format.
+
+## Consequences
+
+- Generated trust policies survive renames and cannot be claimed by a re-registered name.
+- Resolving IDs costs no extra request: the repository lookup is already needed for canonical
+  name casing.
+- Older repositories that have not opted in would get non-matching patterns. [ADR 2](0002-repository-setting-overrides-format-flag.md)
+  mitigates this by reading the repository's actual setting.
+- GitHub Enterprise Server users must pass `--mutable`.

docs/adr/0002-repository-setting-overrides-format-flag.md

@@ -0,0 +1,32 @@
+# 2. Repository setting overrides the format flag
+
+Date: 2026-11-06
+
+## Status
+
+Accepted
+
+## Context
+
+Whether a repository issues immutable or legacy subjects ([ADR 1](0001-immutable-subject-format-by-default.md))
+depends on its creation date and opt-in state, which users often do not know. A pattern in the
+wrong format silently never matches.
+
+`GET /repos/{owner}/{repo}/actions/oidc/customization/sub` returns `use_immutable_subject`.
+The field was observed in API responses but not documented at the time of writing. The request
+can fail for lack of permissions, and the field is absent on GitHub Enterprise Server.
+
+## Decision
+
+If the field can be read, it decides the format, and a note goes to stderr when it differs from
+what the flags asked for. Only when it cannot be read do the default and `--mutable` apply.
+
+## Consequences
+
+- Output matches the repository's actual format without the user having to know it.
+- Users cannot force a format against the repository setting, e.g. to prepare a policy before
+  opting in. Revisit with an explicit override flag if that need appears.
+- If GitHub removes or renames the field, behaviour degrades to the flag-based default rather
+  than failing.
+- Inheritance of an organization-level setting is not verified; the repository endpoint is
+  assumed to report the effective value.