pm-github 2026.10.16 → 2026.10.23

package/README.md

@@ -39,15 +39,26 @@ Only `https://github.com/owner/repo/blob/main/.agents/pm/<folder>/<id>.toon`
 links in PR bodies are recognized. Percent-encoded names and nested SDK tracker
 folders are supported; malformed encodings and traversal segments are ignored. Repository comparisons ignore case. Links to
 other repositories, unknown ids, closed/canceled items and `--skip` ids produce
-explicit skip rows. Bare ids and `pm:` trailers are not supported. If several
-selected PRs reference one item, the lowest PR number supplies its evidence and
-later references are skipped.
+explicit skip rows. A whole-line `Closes <item-id>` or `pm-github: <item-id>`
+declaration, a closing keyword before the canonical item link, or a structured
+`PM item: <item-id-or-canonical-link>` line declares delivery. Spaces and tabs
+are allowed; declarations cannot span lines. Matching uses the complete item ID,
+so `Closes pm-x-extra` cannot deliver `pm-x`. Undeclared canonical links in the
+PR body, including links in follow-up lists (`PM:`), can produce `not_delivery`
+rows for otherwise eligible items with the reason "Mentioned, not delivered".
+Tracker PR URL metadata with no body reference or declaration produces no row.
+
+When several merged PRs declare delivery, closeout selects the latest merge with
+complete merge facts and passing head checks. Equal merge times use the higher
+PR number. Other qualifying claims receive `duplicate_selection`; mention-only
+PRs retain `not_delivery`. All completion fields and the appended close event use
+the selected PR's merge time, merge SHA, head SHA and check evidence.
 
 **A mention is not delivery.** PR bodies routinely link follow-ups, epics and
 related work for context, so a link alone never closes an item. An item is
 closed only when:
 
-- it is `in_progress` (claimed work), **or** its link is preceded on the same
+- its delivery is explicitly declared; a canonical link may be preceded on the same
   line by a GitHub-style closing keyword: `Closes`, `Fixes`, `Resolves` or
   `Delivers` (and their tense forms), for example `- Closes [pm-x](…/pm-x.toon)`;
 - it is not an `Epic`; epics close when their children are done;
@@ -65,14 +76,21 @@ latest status. Check-run, status and ruleset pages are fully read. Rulesets are
 read through GitHub's [effective branch rules API](https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch).
 The check policy reflects the rules readable at invocation time.
 
-When a protection source is unreadable (HTTP 403/404), or no required contexts
-are configured, the report labels the **fallback** rule. Every readable required
-context still must conclude success, including its app binding. The fallback
-additionally requires at least one head check run, every run completed with
-`success`, `neutral` or `skipped`, and successful latest legacy head statuses.
-It never discards a known requirement because another source is unreadable.
-Missing, malformed or incomplete head evidence, malformed metadata and other
-metadata errors fail closed. The plan reports which rule was used.
+When either protection source is unreadable (HTTP 403/404), the row is ineligible
+with `required_checks_unverified`. Observed green runs cannot prove that every
+required context ran. Supply `--required-checks $'test (22)\ntest (26)'` (Bash) to declare a
+newline-separated set of required context names when metadata is unavailable.
+Every declared context must conclude **success** on the exact head (or have a
+successful latest legacy status); missing, pending, neutral or skipped contexts
+refuse closure. Readable requirements remain enforced, including app bindings.
+This **declared** policy does not require unrelated optional runs to succeed.
+When both metadata sources are readable, declarations do not replace their policy.
+
+With fully readable metadata and no required contexts configured, the report
+labels the **fallback** rule: at least one head check run must exist, every run
+must complete with `success`, `neutral` or `skipped`, and latest legacy statuses
+must succeed. Missing, malformed or incomplete evidence and other metadata errors
+fail closed. The plan reports which rule was used.
 
 TOON lists actionable `close`/`refuse` rows individually and summarizes routine skips
 as counts by stable code, for example `skipped: {already_terminal: 30,
@@ -83,7 +101,9 @@ plan row and selected PR check. Global `--json` always returns the full shape
 `{item, pr, action: "close" | "skip", code, reason}`. Codes distinguish
 `head_evidence_unavailable`, `incomplete_merge`, `head_checks_failed`, and
 `head_checks_passed` without parsing explanations. `checks` reports each PR's rule,
-verdict, explanation and successful check names. Dry-run rows describe intended
+verdict, explanation and successful check names. `head_checks_passed` remains the success
+code for all passing policies; `rule: "declared"` proves the caller-declared contexts,
+while repository required-check metadata was unavailable. Dry-run rows describe intended
 closes; `closed` counts writes only with `--apply`. `--dry-run` overrides
 `--apply`. All API planning finishes before the first SDK close. Individual SDK
 refusals become skip rows containing a diagnostic code (or a generic failure
@@ -105,8 +125,11 @@ structured close fields it supports, without overriding tracker policy:
   otherwise `Delivered by the linked pull request, merged after its head check gate passed.`
 - `actual_result`: `Merged at <time>; required checks satisfied; successful head checks:
   <names>` when branch protection or rulesets name required checks (the list holds every
-  successful head check, optional ones included). Under the fallback rule (no readable
-  required contexts) it reads `Merged at <time>; no readable required checks, so every
+  successful head check, optional ones included). Under the declared policy it reads
+  `Merged at <time>; caller-declared checks concluded success; repository required-check
+  metadata was unavailable; successful head checks: <names>`. Under the fallback rule
+  (fully readable, empty policy) it reads
+  `Merged at <time>; no readable required checks, so every
   completed head check run had to succeed, be neutral or be skipped; successful checks:
   <names>`, or `…; no check reported success` when only neutral or skipped runs exist.
   Only the verified merge time, the applied check policy and sorted successful check
@@ -120,6 +143,39 @@ only the tracker; commit it with its history and regenerate the caller's
 changelog in a closeout PR. The [automated closeout workflow](#automated-closeout-workflow)
 performs that daily review-PR preparation for fleet repositories.
 
+## Authenticated webhook reconciliation
+
+`pm github webhook receive <owner/repo> --payload delivery.json --delivery <id>
+--event issues --signature <sha256=...>` accepts explicitly supplied deliveries.
+Set `PM_GITHUB_WEBHOOK_SECRET` through your secret manager. Exact payload bytes
+are authenticated before any write; a durable inbox deduplicates delivery IDs.
+
+`pm github webhook reconcile <owner/repo> --limit 20` reads current GitHub state
+for already-linked issues and returns compact proposals with lifecycle deltas.
+It never applies the event's lifecycle or changes items. Out-of-order events
+therefore cannot reopen a closed item. Output defaults to TOON; add `--json`
+for JSON. Signature and storage refusals include typed codes and remedies.
+
+Use `pm github refresh <owner/repo> --dry-run` to review full changes and
+`--atomic` to apply a fresh polling read. Polling remains the recovery route
+for missed deliveries or unavailable webhooks. Back up the ignored durable
+`github-webhooks` directory inside your tracker. See the
+[CLI and typed SDK example](docs/webhook-inbox.md) for deployment, crash recovery,
+retention and supported-event details.
+
+## Without git
+
+With an explicit repository, GitHub import, export, refresh, sync, project commands,
+blocker checks, closeout and webhook receive/reconcile work in a plain pm tracker
+without a git executable.
+`pm github identity` also works there, entirely offline and without credentials.
+The provider commands still require their normal GitHub access and credentials. Privacy scanning
+with `github gate --diff <file>` also works there. Reading a proposed tracker diff
+with `github gate` requires a git repository; otherwise pass an explicit diff.
+Gated imports (`github import --gate`, including the scheduled sync workflow)
+also require a git repository so the proposed publication can be checked. They
+refuse before writing when the tracker is outside one; plain imports still work.
+
 ## Revalidate GitHub blockers
 
 **Compatibility:** pm-github now requires PM CLI 2026.10.5 or newer for complete
@@ -172,7 +228,7 @@ containing this command before adopting the updated workflow.
 |---|---|
 | `importers` | `pm github import <owner/repo>` — idempotent native import pipeline |
 | `importers` (exporter) | `pm github export` — pm items → GitHub issues (dry-run by default; upsert) |
-| `commands` | `pm gh-issues import` (legacy import alias), `pm github sync` (push status), `pm github gate` (fail-closed pre-push privacy gate), `pm github validate` (diagnostics), `pm github closeout` (verified merged-PR delivery), `pm github project list\|fields\|import\|sync` (Projects v2) |
+| `commands` | `pm github refresh <owner/repo>` (refresh linked items only), `pm gh-issues import` (legacy import alias), `pm github sync` (push status), `pm github gate` (fail-closed pre-push privacy gate), `pm github validate` (diagnostics), `pm github closeout` (verified merged-PR delivery), `pm github project list\|fields\|import\|sync` (Projects v2) |
 | `schema` | declares `github_url`, `github_number`, `github_state`, `github_author`, `github_created_at`, `github_updated_at` item fields |
 | `hooks` | `afterCommand` — opt-in sync reminder (`PM_GITHUB_SYNC`) for linked items |
 | `preflight` | early warning when a mutating github command lacks a token |
@@ -209,6 +265,67 @@ checks.
 
 ## Import
 
+### Keeping a mirror current
+
+Use `refresh` when your tracker deliberately mirrors only a few issues from a busy
+repository. It selects existing `gh:owner/repo#N` tags or explicit `github_url`
+links (also `github_repo` with `github_number`), fetches those numbers in GraphQL
+batches of at most 100, and **never creates items**. Only `/issues/N` URLs are
+refreshable links: the batch query reads issue nodes, so a `/pull/N` URL is not
+selected. Ordinary references in text
+are not links. Conflicting identities or multiple owners fail before any write.
+
+```sh
+pm github refresh owner/repo --dry-run --json
+pm github refresh owner/repo --atomic
+pm github refresh owner/repo --since 7d --limit 50 --dry-run
+```
+
+`--limit` bounds the selected issue numbers, in ascending order, before fetching.
+`--since` filters by the fetched upstream update time, including closed issues;
+filtered items are counted separately. Omit it for a complete refresh. A GitHub
+token is required for GraphQL (`GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth login`).
+Closure evidence uses the importer's timeline reader; label pages are fetched in
+full. API retries and rate limits use the shared transport.
+
+Refresh reuses import's title, labels and source lifecycle mapping, including
+real closure/completion dates and reopening. Body, local item type, assignee and
+milestone are preserved. A `release` already present on the item is only replaced
+when GitHub supplies calendar-tag attribution for a closure; open issues and
+closures without a matching tag keep the existing release, so user- or tool-set
+attribution survives. Existing cross-provider link-only owners retain their
+native lifecycle and content, as on import. TOON (default) or `--json` returns a
+`plan` of `{id, number, changes: [{field, old, new}]}` plus `updated`, `unchanged`,
+`missing`, `filtered`, `selected`, `resumed` and `created: 0`. On dry-run, `updated` means
+would update; nothing is written. Missing rows carry a typed `reason` and remain
+unchanged: `not_found_or_inaccessible` (GitHub cannot distinguish deleted/hidden),
+`inaccessible`, `transferred`, `api_error`, `incomplete_response`, or `invalid_issue`.
+A request-wide failure aborts before new refresh writes. Recovery of unfinished
+transactions happens first and may already have committed earlier writes when
+a subsequent request fails.
+
+Each changed item receives an audit comment. `--atomic` applies the batch in one
+SDK workspace writer transaction with rollback; otherwise each changed item gets
+its own transaction. Every update transaction persists its exact plan beside the
+SDK journal before writing. If a run dies mid-transaction, the next refresh
+detects unfinished journals for the selected items, validates every saved plan
+before any replay, and refuses recovery from another repository. It replays the original
+plan — committing the journal without duplicating the audit comment — before
+unchanged items are skipped, and reports it in `resumed`. A preview
+(`--dry-run`) refuses while such a journal is open; a missing plan fails closed
+naming the transaction id instead of silently reporting a no-op. Review the preview before publishing tracker changes and
+apply the existing privacy gate to any proposed commit.
+
+For a weekly refresh, run this in a checkout with the extension installed, token
+available and `PM_PATH` set to the intended tracker. For example, a cron entry:
+
+```cron
+0 6 * * 1 cd "$MIRROR_CHECKOUT" && pm github refresh owner/repo --atomic --json >> "$MIRROR_LOG" 2>&1
+```
+
+Configure those environment variables in the crontab. The command updates the
+tracker locally; review and commit changes using your normal workflow.
+
 ### `pm github import <owner/repo>` (or `pm gh-issues import`)
 
 ```bash
@@ -244,6 +361,7 @@ pm github import owner/repo --dry-run
 | `--with-comments` | boolean | Fetch issue comments and append them to the item body |
 | `--comments-mode <mode>` | `body`\|`annotations`\|`both` | How fetched GitHub comments are persisted (default `body`). `annotations` syncs comments into the pm item's native comments collection via the SDK; `both` writes the body section AND native comments. `annotations`/`both` are idempotent on re-import (dedupe by GitHub comment id) |
 | `--atomic` | boolean | Commit every create, update, close, and reopen in one workspace-writer-locked, crash-resumable transaction (requires pm CLI/SDK >=2026.7.20). Normal failure compensation restores updated/closed items and deletes newly created items; an incomplete compensation is reported explicitly for retry or repair. |
+| `--adopt-cited` | boolean | Explicitly opt in to conservative citation adoption (default: off). Tag new items `gh:owner/repo#N` instead. Default imports only report citation candidates. |
 | `--link-deps` | boolean | After import, map dependency references in issue **bodies** (`Blocked by #N`, `Depends on owner/repo#N`, `Blocks #N`) to pm dependency edges between the linked items. Idempotent, best-effort, and re-runnable; see [Dependency linking](#dependency-linking---link-deps) below. |
 | `--gate` | boolean | Fail-closed privacy gate: verify plan completeness (every fetched issue accounted for exactly once) and provenance idempotency (every re-import lands on exactly one `gh:owner/repo#N`-tagged item) BEFORE the write, then scan the proposed tracker change with [`pm github gate`](#pm-github-gate) AFTER it. Any finding — or any unreadable scan input — exits non-zero so an automated pipeline can never commit or push the change. Embeds `gate` receipts in the result. |
 | `--dry-run` | boolean | Preview without writing |
@@ -251,6 +369,74 @@ pm github import owner/repo --dry-run
 
 Each imported item records GitHub provenance: the `gh:owner/repo#N` idempotency tag, a `github_author:<login>` tag, and an enriched description (`author @<login> · state reason <reason> · created <iso> · updated <iso>`). GitHub issues closed as `not_planned` import as pm `canceled` instead of `closed`, preserving the difference between completed work and deliberately dropped work. The integration declares the `github_url`, `github_number`, `github_state`, `github_author`, `github_created_at`, and `github_updated_at` schema fields.
 
+The primary way to prevent duplicate imports is to tag an item
+`gh:owner/repo#N` **when it is created**, for example
+`pm create issue "Fix widget behavior" --tags "gh:acme/widgets#30"`.
+For an existing item, use `pm update <id> --add-tags "gh:acme/widgets#30"`. A prose URL is context, not an
+ownership declaration. Existing tag/structured URL/provider matching takes
+precedence and is unchanged.
+
+**Citation adoption is off by default.** Manual imports, the legacy alias and
+scheduled gated syncs retain normal create behavior when explicit ownership is
+absent. They report read-only `citation_candidates` so an agent can tag the
+correct item, including when several candidates exist. No candidate is adopted
+or ambiguity-blocked by default.
+
+Use `--adopt-cited` on the CLI, `adoptCited: true` in SDK import options, or
+`adopt-cited: true` on the reusable sync workflow to enable the fallback. The
+fallback deliberately favors refusal over overwriting an unrelated item:
+
+1. **Normalize before checking.** Decode complete named/numeric HTML entities and
+   percent-encoded bytes repeatedly until stable, bounded to eight passes.
+   Apply NFKC and remove zero-width/bidi control characters. Unwrap Markdown
+   link destinations and reference definitions and join soft line breaks for
+   intent matching. Retain normalized source as well as the unwrapped view for
+   exclusion, so a link label cannot hide a second reference. Joined-line views
+   also expose split references. A normalization bound exhaustion is a refusal.
+2. **Allowlisted ownership.** A qualified target issue reference must appear in
+   the title, directly follow `Fix`, `Fixes`, `Fixed`, `Close`, `Closes`, `Closed`,
+   `Resolve`, `Resolves` or `Resolved` at the start of the description, or be a
+   URL on a whole body line `Issue: <url>` or `Tracks: <url>`. Matching ignores
+   case. Body fix phrases, `Related:` mentions, unanchored phrases and bare
+   numbers cannot authorize adoption.
+3. **Exclude every other reference.** Across all normalized fields, any other
+   `github.com` URL, foreign repository, different `#<digits>` or
+   `issues`/`pull` token followed by another number vetoes adoption. Unattributed
+   paths/bare hashes also refuse adoption: this item projection has no verified
+   owning-repository context. PR URLs, including a same-number PR URL, are other
+   URLs. The scan over-counts code and incidental text deliberately. These
+   checks reduce risk; they do not make arbitrary prose an ownership contract.
+
+| Existing prose | Default | With `--adopt-cited` |
+| --- | --- | --- |
+| Description: `Fixes acme/widgets#30` | Create + `adoption_disabled` hint | Eligible if no other reference |
+| Body line: `Issue: https://github.com/acme/widgets/issues/30` | Create + hint | Eligible if no other reference |
+| Title: `Handle acme/widgets#30` | Create + hint | Eligible if no other reference |
+| Body: `Fixes acme/widgets#30` | Create + `missing_intent` hint | Create + hint |
+| Body: `Related: acme/widgets#30` | Create + `missing_intent` hint | Create + hint |
+| Title cites issues 30 and 31 | Create + `multiple_issues` hint | Create + hint |
+| Description fixes issue 30; body has `**https://github.com/other/widgets/issues/30**` | Create + hint | Create + `multiple_issues` hint |
+| Description fixes issue 30; body has `[other](https://github.com/other/widgets/issues&sol;31)` or `issues%2F31` | Create + hint | Create + `multiple_issues` hint |
+
+Plans include `citation_candidates: [{id, reason}]`; aggregate dry-run and write
+receipts include `citation_candidates: [{issue, id, reason}]`. Reasons are
+`adoption_disabled`, `missing_intent`, `multiple_issues`, `normalization_limit` or `structured_owner` (the item already carries a `github_*` field, a core `external_ref` or `source_owner`, a `linear_*`/`jira_*`/`ado_*` identity field, provider provenance, a GitHub issue URL in its links or a native declaration, so prose citing another issue never re-owns it).
+Candidate reporting never changes the referenced item's status, content or
+fields, including a closed item's completion state.
+
+With explicit opt-in, one eligible untagged candidate produces an `adopt` plan:
+its ID receives the provenance tag and `github_*` fields through normal upsert.
+Closed/canceled owners remain eligible. Two or more eligible owners refuse the
+batch with typed `ambiguous_citation`, IDs and a remedy to tag the correct item.
+The default path never applies that fallback ambiguity refusal. Existing
+structured-identity collision checks still apply in both modes.
+
+Dry runs show `adopt` and `wouldAdopt`; write receipts report `adopted` separately
+from `imported`/`updated`. Gated idempotency counts an opt-in adopt as one landing
+item. Status push, export and Projects matching retain their scope. Citation
+reporting and opt-in adoption work in non-git trackers; actual `--gate` writes
+still require a Git worktree for the proposed-change privacy scan.
+
 `--issue` deduplicates references and fetches each selected issue directly, including closed issues, without listing the repository. Every selected number is fetched and checked before any tracker write. A missing number fails the whole import; `--dry-run` instead reports `missingIssues` and previews the available selection. Pull request numbers require `--include-prs`. Selection combines with comment modes, dependency linking, atomic imports, gates, dry runs, and custom item types, preserving provenance-based re-import idempotency.
 
 `--limit` bounds the matching list after PR, draft, and milestone filters. Pagination stops once one extra matching issue establishes truncation, so at most `n + 1` eligible issues are retained; GitHub pages may also contain excluded entries. Without a limit, existing list ordering is unchanged.
@@ -448,7 +634,83 @@ Unreadable input, malformed or truncated diffs, binary input, invalid UTF-8, Git
 
 Rendered values are also scanned in memory before mutation, so a known finding cannot be written to disk. After mutation, the importer verifies that every planned provenance tag exists exactly once, then scans the tracker diff. A completed SDK journal cannot substitute for missing item files.
 
-The `gate` receipt reports the verdict, scanned file count, findings, and allowlisted count. With `--json`, successful reports go to stdout; failures use the host CLI's JSON error envelope on stderr, with the redacted gate report serialized in `detail` (`jq ' .detail | fromjson ' gate-error.json`). Unreadable inputs produce a nonzero JSON refusal.
+The `gate` receipt reports the verdict, scanned file count, findings, and allowlisted count. Each finding includes `match_offset` (the starting character offset of the hashed match within the scanned field value, or the serialized added line for tracker text) and `excerpt`. Host-path excerpts show only the root initial, such as `/h***/…`; other matches use `[redacted]`. Human-readable workflow diagnostics include the same evidence. Full paths and secrets never appear. Recognizable bare-root JavaScript regex literals immediately used with `.test()` or `.exec()` are distinguished from paths; quoted host paths and slash-separated host paths remain refused, including inside code and regex source. Ambiguous quote contexts remain refused. Whole JSON-serialized fields retain the same distinction after decoding; TOON wrappers are recognized only in tracker text.
+
+With `--json`, successful reports go to stdout; failures use the host CLI's JSON error envelope on stderr, with the redacted gate report serialized in `detail` (`jq ' .detail | fromjson ' gate-error.json`). Unreadable inputs produce a nonzero JSON refusal.
+
+## Self-versioned workflows and Dependabot
+
+Both reusable workflows resolve their own **exact** pm-github release version at
+runtime and verify the installed package version. GitHub's documented
+[`job.workflow_sha`](https://docs.github.com/en/actions/reference/workflows-and-actions/contexts#job-context)
+is the commit of the workflow that defines the current job, including a reusable
+workflow. `github.job_workflow_sha` is not a documented context property;
+`job_workflow_sha` is an OIDC claim. The caller checkout and caller commit are
+never used to discover the reusable workflow's version. These workflow identity
+context properties are not available on GitHub Enterprise Server.
+
+The resolver uses public `git ls-remote --tags https://github.com/unbraind/pm-github
+'refs/tags/v*'`. It matches lightweight tags directly and annotated tags by their
+peeled `^{}` commit (never the tag object), strips `v`, and requires an exact
+numeric version `N.N.N` or `N.N.N-N`. It reads all matching refs in one request,
+without API pagination or new credentials. Lookup errors and multiple release
+versions on one commit fail closed. Release version discovery needs no GitHub App, and no release-time workflow
+stamping is required. The release workflow keeps its existing token behavior.
+
+Pin **release commit SHAs**, with their matching tag in a same-line comment
+(for example `uses: unbraind/pm-github/.github/workflows/pm-github-sync.yml@<40-character-release-sha> # v2026.10.16`).
+New callers omit `pm-github-version`. If no release tag matches the workflow
+commit, the job fails with instructions to pin a release SHA. For compatibility,
+a nonempty deprecated input provides an exact-version fallback with a warning
+only when no tag matches. If a tag matches and the input differs, the job warns
+and uses the tag version. Untrusted input is passed through `env:`, never inserted
+into shell source or warning text. No `latest`, range, or floating install tag is used.
+
+GitHub documents [reusable-workflow updates](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/auto-update-actions)
+and [SHA pins and same-line version comments](https://docs.github.com/en/code-security/reference/supply-chain-security/supported-ecosystems-and-repositories#github-actions).
+Dependabot updates SHA-pinned remote `uses:` references and their version comments
+when the pinned commit has a matching release tag. GitHub warns that untagged
+commits can instead advance to the latest commit, which may differ from the latest
+release. A SHA update therefore selects the new runtime-resolved install version without
+editing any caller input.
+
+Merge this entry into the caller's `.github/dependabot.yml` (retain other ecosystems
+and disjoint groups such as `codeql-action`):
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 5
+    groups:
+      pm-toolchain:
+        patterns:
+          - "unbraind/pm-github"
+        # No update-types filter: calendar-version year changes must also update.
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "github_actions"
+```
+
+The group pattern is the repository name, covering both reusable workflow paths.
+Use exactly `pm-toolchain`: the fleet's existing
+[dependabot-auto-merge.yml](.github/workflows/dependabot-auto-merge.yml) enables
+`gh pr merge --auto --squash` for Dependabot PRs in that group, including calendar
+version major changes. The workflow checks the Dependabot author and repository
+owner, then the metadata group or minor/patch update type. Commit prefix and
+labels do not control merge eligibility; the explicit values above keep PRs
+consistent. Ensure the two labels exist (GitHub ignores unknown custom labels).
+Repository auto-merge must be enabled and required branch-protection checks must
+pass; this configuration does not bypass them. It uses the existing workflow's
+`contents: write` and `pull-requests: write` token permissions. See GitHub's
+[Dependabot option definitions](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference)
+for schedules, groups, commit messages and labels.
 
 ## Automated closeout workflow
 
@@ -456,10 +718,10 @@ The `gate` receipt reports the verdict, scanned file count, findings, and allowl
 is a reusable `workflow_call` that opens or updates **one** PR titled
 `chore(pm): close items delivered by merged pull requests` from `pm-github/closeout`.
 Copy [the caller template](docs/closeout-workflow-caller.yml) into the caller's
-workflows directory and replace `RELEASE_COMMIT_SHA` and `RELEASE_VERSION` with a
-reviewed workflow commit and an exact published pm-github version containing
+workflows directory and replace `RELEASE_COMMIT_SHA` with a reviewed release
+commit and `vRELEASE_VERSION` with its matching release tag containing
 `github closeout`. The template schedules a daily run and allows manual dispatch.
-Adopting callers is a separate change; the existing sync workflow is unchanged.
+Adopting callers is a separate change.
 
 The workflow resolves the caller's default branch through the repository API,
 with event metadata as fallback, and refuses other run refs before checkout.
@@ -467,7 +729,25 @@ This works for scheduled payloads without a `repository` object and for branches
 such as `trunk` or `release/stable`. The caller's pinned PM CLI comes from
 `npm ci --ignore-scripts` in `npm-project-dir` (default `.`), which must resolve
 inside the workspace and contain `package.json`. The SDK resolves the tracker
-from the repository root. The exact `pm-github-version` is installed and verified.
+from the repository root. The exact release version resolved from the workflow commit is installed and verified.
+
+`required-checks` is an optional workflow input with an empty default. Set it to
+all required context names, **one context name per line**, when the token cannot read
+branch-protection or ruleset metadata, as is common with `GITHUB_TOKEN`:
+
+```yaml
+with:
+  required-checks: |
+    test (22)
+    test (26)
+```
+
+Each line is trimmed and empty lines are ignored. Spaces within names such as
+`CI / build` are preserved; names are never split on spaces. The workflow passes
+the newline-joined list as one quoted command argument for TypeScript to parse.
+Without a declaration, unavailable
+metadata refuses closeout and prevents publishing a branch or PR. Keep this list
+aligned with the caller's required checks; it is a caller-owned policy declaration.
 
 Each run rebuilds the bot branch from the current default branch and invokes
 `pm github closeout --since 1970-01-01 --apply --json`. Scanning all merge history
@@ -488,23 +768,58 @@ The script must emit the root `CHANGELOG.md` and remain inside the publication s
 | Validation | Strict PM health; explicit item/history scope committed together |
 | Branch and PR | Explicit force-with-lease against the observed bot ref; push only bot branch; owned PR lookup excludes forks |
 | No-op | Zero closes or no tracker diff creates no remote branch or PR; caller-only drift unpublished; stale owned PR closed |
-| CI | Caller workflow dispatch after PR create/update; parked approval-required runs reported; no merge |
-
-`ci-workflows` defaults to `ci.yml`; use whitespace-separated filenames for every
-required caller CI workflow. Each must support `workflow_dispatch` and produce
-its required checks on that event. Missing files are skipped with a notice,
-matching sync; empty disables dispatch. CI dispatch starts checks; it does not
-certify that they passed. Review and required-check enforcement remain with the
-caller's protected branch. A repository concurrency group serializes closeout
-runs, and the explicit lease rejects competing writers.
-
-The caller grants only `contents: write`, `pull-requests: write`, `checks: read`
+| CI and landing | Dispatch caller checks after publication and branch refresh; request protected squash auto-merge in App mode; report parked approval-required runs |
+
+`ci-workflows` defaults to `ci.yml codeql.yml`, covering the fleet's CI and
+CodeQL workflows without querying branch protection. An explicit list replaces
+that inventory (use `ci.yaml` or `codeql.yaml` when appropriate). Missing files
+emit a notice; existing files without a recognized `workflow_dispatch` trigger
+emit a warning naming the one-line repair. Standard block triggers and compact
+`on: workflow_dispatch` / `on: [pull_request, workflow_dispatch]` forms are
+supported. Each dispatched workflow must emit its required context names on
+that event. Zero dispatchable workflows fails; `""` deliberately disables both
+dispatch and automatic landing. Dispatch errors fail the run.
+
+GitHub does not evaluate `workflow_dispatch` job checks for PR branch rules,
+even when those checks pass on the head SHA. For unattended landing, configure
+`automation-app-client-id` and the optional `automation_app_private_key` secret.
+After the local gates, the pinned official App-token action mints a token for
+only the caller repository, with contents/pull-requests/actions write and
+checks/statuses read. Publication and refresh use that token, so native
+`pull_request` workflows run without the GITHUB_TOKEN approval prompt and
+provide eligible required checks. Manual head dispatch remains additional
+verification. Empty credentials retain GITHUB_TOKEN and emit a setup notice;
+partial or failed App credentials stop publication. The private key is passed
+only to the token action, after caller scripts have completed.
+
+In App mode, after dispatch the workflow requests `gh pr merge --auto --squash`
+with the expected head SHA. A repository that disallows auto-merge emits a notice.
+Without an App, maintainers approve native PR runs, wait for required checks and
+conversations, and merge with an authorized credential; the workflow does not arm
+auto-merge.
+GitHub enforces required checks and conversation resolution. The same run
+polls once per minute: when the PR is `BEHIND`, it requests a branch update
+against the expected head, then dispatches all selected workflows and, in App
+mode, requests auto-merge again when the new head appears. App mode stops within
+forty minutes, inside its token's one-hour lifetime; legacy mode has a two-hour bound. The
+existing daily schedules and separate sync/closeout concurrency groups remain.
+A base change after the monitor window waits for the next daily rebuild.
+Unresolved conversations continue to block landing.
+
+See [the caller audit and one-time setup](docs/bot-pr-automation.md) for the App
+credential mapping, CodeQL trigger changes and explicit CI overrides. GitHub
+documents [the token approval behavior](https://docs.github.com/en/actions/concepts/security/github_token)
+and [why manual job checks do not satisfy PR branch rules](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks).
+
+The caller template uses top-level `permissions: {}` and grants its
+`gated-closeout` job only `contents: write`, `pull-requests: write`, `checks: read`
 and `actions: write`. Closeout uses `checks: read` instead of sync's `issues: read`
 to retrieve head-check evidence ([GitHub Checks API permissions](https://docs.github.com/en/rest/checks/runs#list-check-runs-for-a-git-reference)).
 The reusable workflow cannot elevate the caller's token
 permissions ([GitHub reusable workflow permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations)).
 Repository Actions settings must allow Actions to create PRs. Read denial stops
-closeout before push with a diagnostic, including unavailable head-check evidence
+closeout before push with a diagnostic, including `required_checks_unverified` and
+unavailable head-check evidence
 reported by the command as a skip when it blocks a local, existing, non-terminal,
 non-excluded tracker item. Unlinked PRs and foreign/terminal/excluded links do
 not fail the run for unavailable evidence. Incomplete merge facts use a separate
@@ -535,11 +850,13 @@ Optional inputs:
 
 | Input | Default | Behavior |
 | --- | --- | --- |
+| `adopt-cited` | `false` | Explicitly enable conservative normalized citation adoption for preview, import and repeat verification. Primary prevention is creating items with `gh:owner/repo#N` tags. Leave false to retain normal creates with read-only candidate hints. |
 | `npm-project-dir` | `.` | Relative npm project directory for `npm ci --ignore-scripts`, the CLI `node_modules/.bin` PATH entry, and `post-import-script`. Must have `package.json`, contain no `..` segments, and resolve inside the workspace (including symlinks); invalid paths fail before caching/install. The tracker and publication scope stay at the repository root. |
 | `post-import-script` | `changelog:full` | Caller npm script name invoked with `npm run --if-present` after import and before the final scan. Override for a different package script, or set `""` to disable. Missing scripts are skipped. Raw shell commands are not accepted. Generated `CHANGELOG.md` is staged with the tracker. Changing any file outside the documented scope fails the run, whether staged, unstaged, or untracked. |
-| `ci-workflows` | `ci.yml` | Whitespace-separated filenames in the caller's `.github/workflows`, for example `ci.yml codeql.yml`. Missing files emit a notice and are skipped; set `""` to disable dispatch. Existing workflows must enable `workflow_dispatch`; dispatch errors fail the sync job. |
+| `automation-app-client-id` | `""` | Optional GitHub App client ID, paired with the `automation_app_private_key` workflow-call secret. Enables eligible native PR runs through a fresh repo-scoped token; absent credentials retain GITHUB_TOKEN with a notice. |
+| `ci-workflows` | `ci.yml codeql.yml` | Explicit whitespace-separated filename override in the caller's `.github/workflows`. Missing/non-dispatchable workflows are reported; zero dispatchable workflows fails. Empty disables dispatch and auto-merge. See the CI and landing contract above. |
 
-A fleet repo owns the schedule and calls it with the pinned versions (see [`docs/sync-workflow-caller.yml`](docs/sync-workflow-caller.yml)):
+A fleet repo owns the schedule and calls it with a pinned release SHA (see [`docs/sync-workflow-caller.yml`](docs/sync-workflow-caller.yml)):
 
 ```yaml
 name: Sync GitHub issues into pm
@@ -556,12 +873,15 @@ permissions:
 
 jobs:
   gated-sync:
-    uses: unbraind/pm-github/.github/workflows/pm-github-sync.yml@RELEASE_COMMIT_SHA
+    uses: unbraind/pm-github/.github/workflows/pm-github-sync.yml@RELEASE_COMMIT_SHA # vRELEASE_VERSION
     with:
-      pm-github-version: "RELEASE_VERSION"     # required: exact published version
+      automation-app-client-id: ${{ vars.PM_GITHUB_APP_CLIENT_ID }}
+      adopt-cited: false # Tag new items gh:owner/repo#N; opt in only for deliberate adoption.
+    secrets:
+      automation_app_private_key: ${{ secrets.PM_GITHUB_APP_PRIVATE_KEY }}
 ```
 
-Replace the two release placeholders with the release commit and package version containing this change; existing callers must repin both. The selected npm project needs a committed npm lockfile (`package-lock.json` or `npm-shrinkwrap.json`) and `@unbrained/pm-cli` as a devDependency (the workflow's `npm ci` provides the CLI) and its pm tracker at `.agents/pm` committed on the caller's default branch. Under **Settings → Actions → General → Workflow permissions** it must allow read and write token permissions and enable **Allow GitHub Actions to create and approve pull requests** (an organization can disable this), or the run pushes the sync branch and then fails to open the review PR. The caller must grant `actions: write`; a reusable workflow cannot elevate its caller's permissions.
+Replace `RELEASE_COMMIT_SHA` with a reviewed release commit containing this change and `vRELEASE_VERSION` with its matching tag. Configure [Dependabot](#self-versioned-workflows-and-dependabot) to maintain future pins automatically. The selected npm project needs a committed npm lockfile (`package-lock.json` or `npm-shrinkwrap.json`) and `@unbrained/pm-cli` as a devDependency (the workflow's `npm ci` provides the CLI) and its pm tracker at `.agents/pm` committed on the caller's default branch. Under **Settings → Actions → General → Workflow permissions** it must allow read and write token permissions and enable **Allow GitHub Actions to create and approve pull requests** (an organization can disable this), or the run pushes the sync branch and then fails to open the review PR. The caller must grant `actions: write`; a reusable workflow cannot elevate its caller's permissions.
 
 For a caller such as `unbraind/pm-rust` with no root `package.json`, add
 `npm-project-dir: tests/oracle` under `with:`. Its `tests/oracle/package.json`
@@ -569,7 +889,16 @@ provides the CLI and post-import npm script; Git and pm tracker operations still
 run from the repository root. A script that regenerates the changelog must write
 the repository-root `CHANGELOG.md` to stay within the publication allowlist.
 
-Bot-created review PRs may have missing required checks or `pull_request` runs parked in `action_required`. After a successful push and PR creation/update, the reusable workflow uses the job's `GITHUB_TOKEN` to run `gh workflow run <file> --ref "$SYNC_BRANCH"` for each configured caller CI workflow. Explicit `workflow_dispatch` creates runs on the sync head, so callers must enable that trigger and ensure those runs produce their required check names (and do not restrict the required jobs to the `pull_request` event). It also lists `action_required` runs for the exact pushed SHA and prints their URLs as notices without failing because approval is needed. Missing workflows, disabled dispatch, or approval notices do not establish that required CI passed; inspect the dispatched checks. A no-change sync closes its stale own review PR and dispatches nothing. See GitHub's [GITHUB_TOKEN event rules](https://docs.github.com/en/actions/concepts/security/github_token) and [dispatch trigger and permission requirements](https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event).
+Bot-created PRs using GITHUB_TOKEN may have `pull_request` runs parked in
+`action_required`. The optional App token makes publication and branch refresh
+start native eligible PR workflows automatically. Configured manual workflows
+are also dispatched on the bot head; these jobs are additional verification,
+because GitHub excludes manual job checks from PR branch-rule evaluation. Each
+manual workflow must support `workflow_dispatch` and produce its intended check
+names on that event. Parked-run notices include their URLs. A no-change sync
+closes its stale owned review PR and dispatches nothing. See GitHub's
+[token event rules](https://docs.github.com/en/actions/concepts/security/github_token)
+and [required-check eligibility](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks).
 
 ### Installed CLI timeout acceptance
 
@@ -612,6 +941,10 @@ Release checks require type checking, docstrings, ESLint, zero source duplicatio
 
 `npm run changelog:full` reads the complete tracker through the SDK and feeds pm-changelog. Closed work supplies release history; the explicit `changelog-unreleased` tag includes a pending candidate without closing its PM item. Other open work stays excluded.
 
+Daily Release measures the successful `test (22)` and `test (26)` jobs from the last 20 successful main push CI runs. Its merge wait is the nearest-rank p95 duration plus the larger of 15 minutes or 25%, bounded to 60–120 minutes. Missing history uses the 60-minute floor. The log and job summary record the samples, p95, margin and bounds; the job timeout is 360 minutes.
+
+A main advance during preparation or waiting can update the release branch once. Every intervening commit must preserve `package.json` and lockfile release versions, `CHANGELOG.md`, `manifest.json`, and release notes, including changes later reverted. Dependency-only changes are eligible. A conflict, metadata change, non-ancestor main, or second advance aborts. A successful update uses a head-specific push lease, restarts the full measured wait, and requires protected checks on the new head. Publication still verifies the merged commit and runs the release gate again.
+
 ## Multi-agent merge safety
 
 This repo tracks its project management in `.agents/pm/` and ships a committed `.gitattributes`
@@ -628,3 +961,50 @@ itself lists each affected stream in its output; `pm history --verify <id>` spot
 content, so `reconcile` only re-greens the hash chain (no data loss) — see the authoritative
 [pm-cli merge-safety guide](https://github.com/unbraind/pm-cli/blob/main/docs/MERGE_SAFETY.md). The
 older blunt `pm history-repair --all` remains available as a lower-level primitive.
+
+## What an imported issue looks like
+
+An issue owned by the GitHub importer keeps GitHub's creation and closure dates in the native lifecycle fields used by momentum and cycle-time readers. The import records a new, append-only before/after history event at the time of synchronization; it does not rewrite old events. The public SDK's high-level create/update commands reserve these dates, so finalization uses its public item lock, serialization and history primitives.
+
+```yaml
+status: closed
+created_at: "2026-09-02T10:00:00Z"
+updated_at: "2026-10-16T12:00:00Z"
+closed_at: "2026-09-04T12:00:00Z"
+completed_at: "2026-09-04T12:00:00Z"
+close_reason: 'Closed on GitHub as completed on 2026-09-04T12:00:00Z; closing PR https://github.com/example/project/pull/8 ("Restore the parser")'
+release: v2026.9.5
+github_url: https://github.com/example/project/issues/7
+github_number: 7
+github_state: closed
+github_state_reason: completed
+github_created_at: "2026-09-02T10:00:00Z"
+github_updated_at: "2026-09-04T12:00:00Z"
+github_closed_at: "2026-09-04T12:00:00Z"
+github_release: v2026.9.5
+github_link_only: false
+```
+
+`completed` maps to `closed`; `not_planned` and `duplicate` map to `canceled`. An open or reopened issue maps to `open` and clears old closure evidence and import-assigned release attribution. A closure reason names the closing commit from the REST timeline or closing PR/commit identified by GraphQL `ClosedEvent`, when available. A `ConnectedEvent` supplies a quoted linked PR without claiming that the association caused the closure. Otherwise it says `Closed on GitHub as <reason> on <date>`. Closing a report alone does not establish that its described defect or privacy exposure was repaired.
+
+Release attribution uses the actual dates of locally available calendar tags, including annotated tag dates. A closed issue belongs to the first tag at or after its closure: before the first tag goes to that first release, between two tags goes to the second, and after the latest tag remains pending. Fetch the complete tag history before importing; the reusable sync workflow already does this. Regenerate with pm-changelog's `--respect-item-release` so a historical import stays in its declared release window.
+
+Before creating an item, import checks the complete tracker for its provenance tag, GitHub URLs in provenance or link metadata, and Linear/Jira/ADO links referenced by the GitHub issue body. A unique existing external owner receives the GitHub tag and source metadata; its title, body, provider identity, creation/completion dates and release remain intact. A persisted `github_link_only` marker preserves that ownership on subsequent syncs. Free-text descriptions and bodies do not declare GitHub ownership. Ambiguous matches refuse the import before writes with `--gate` or `--atomic`. A plain multi-issue import may write earlier issues before rejecting a later ambiguous match.
+
+With `--gate` and a nonempty filtered issue list, both preview and apply results include a `plan` with source dates, closure reason, release, target identity, link/create/update action and state-conflict decision. An empty filtered issue list returns without a `plan`, including with `--gate --dry-run`. GitHub wins lifecycle conflicts for GitHub-owned imports. A canceled item that GitHub later reports as completed uses the SDK's explicit repeat-closure transition with the source reason. A linked external owner keeps its local status, and the plan records `preserve-provider-owner`; `github_state` still records the source state. Atomic transaction identity includes the latest external edit or different lifecycle generation in history. Local state edits and repeated state cycles force reconciliation, while staging and compensation keep crash retries on the same journal. Finalization runs before the SDK commits and is compensated with the batch on failure. It is idempotent and runs again after a recovered atomic journal, so an interrupted finalization can be repaired by retrying the same import before the gate permits a push.
+
+SDK limitation: native `updated_at` remains the local mutation clock because the bulk SDK uses it to address rollback history. The GitHub update date is retained exactly in `github_updated_at`, and the gated plan discloses this policy. Backdating native `updated_at` safely requires an SDK import mutation whose version identity is independent of source time. Native creation, closure and completion dates still preserve GitHub lifetimes for momentum and cycle-time readers.
+
+## Provider identity collisions
+
+Use `pm github identity --json` for a bounded offline graph of conflicting
+`external_ref`, GitHub provenance tags and native/provider ownership. Copied
+prose appears as a weaker mention; genuine provider links retain distinct
+ownership evidence. Inspect one group with
+`pm github identity --identity 'gh:example/project#7'`.
+
+Preview a narrowly scoped repair with `--identity`, `--owner` and `--detach`;
+apply only after reviewing its exact `--approve` digest. Ambiguous identities
+refuse with typed remedies. The SDK supplies complete reads, semantic preview,
+writer transactions, immutable audit history and idempotent replay. See the
+[worked example and SDK contracts](docs/identity-collisions.md).