pm-github 2026.10.16 → 2026.10.19

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2026.10.19 - 2026-10-19
+
+### Added
+
+- Preserve imported GitHub lifetimes, closure evidence and release attribution while linking cross-provider items ([pm-github-c093](https://github.com/unbraind/pm-github/blob/main/.agents/pm/features/pm-github-c093.toon))
+
+### Fixed
+
+- Require explicit delivery attribution before merged-PR closeout ([pm-github-uqjf](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-uqjf.toon))
+- The daily release regenerates the changelog with a different status filter than release:check, so an open changelog-unreleased item delivered since the last tag fails the release ([pm-github-l1ot](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-l1ot.toon))
+- Release timeout must report current workflow approval state ([pm-github-b145](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-b145.toon))
+- Preserve legacy GitHub ownership across copied provider examples ([pm-github-b143](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-b143.toon))
+- Reject malformed effective-rule discriminators before closeout ([pm-github-b141](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-b141.toon))
+
 ## 2026.10.16 - 2026-10-16
 
 ### Added

package/README.md

@@ -39,15 +39,17 @@ 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. Bare mentions and `pm:` trailers are not delivery evidence. Use a whole-line
+`Closes <item-id>` or `pm-github: <item-id>` declaration, a closing keyword before
+the canonical item link, or an item field `github_pr`, `pr_url` or
+`pull_request_url` containing the exact PR URL. Multiple merged PRs explicitly
+claiming one item are reported as `ambiguous_delivery`; none closes it.
 
 **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 +67,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 +92,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 +116,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
@@ -450,16 +464,90 @@ Rendered values are also scanned in memory before mutation, so a known finding c
 
 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.
 
+## 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
 
 [`.github/workflows/pm-github-closeout.yml`](.github/workflows/pm-github-closeout.yml)
 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 +555,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 +594,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
@@ -537,9 +678,10 @@ Optional inputs:
 | --- | --- | --- |
 | `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 +698,14 @@ 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 }}
+    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 +713,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
 
@@ -628,3 +781,36 @@ 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.

package/dist/closeout.d.ts

@@ -16,12 +16,12 @@ export interface CloseoutRow {
     code: CloseoutCode;
 }
 /** Stable decisions used by automation and compact skip counts. */
-export type CloseoutCode = "already_terminal" | "other_repository" | "duplicate_selection" | "explicit_skip" | "unknown_item" | "epic" | "active_children" | "not_delivery" | "close_failed" | "head_checks_passed" | "head_checks_failed" | "head_evidence_unavailable" | "incomplete_merge";
+export type CloseoutCode = "already_terminal" | "other_repository" | "duplicate_selection" | "explicit_skip" | "unknown_item" | "epic" | "active_children" | "not_delivery" | "close_failed" | "ambiguous_delivery" | "head_checks_passed" | "head_checks_failed" | "head_evidence_unavailable" | "required_checks_unverified" | "incomplete_merge";
 /** Which head-check policy was evaluated for one selected pull request. */
 interface CheckGate {
     pr: number;
     code: CloseoutCode;
-    rule: "required" | "fallback" | "unavailable";
+    rule: "required" | "declared" | "fallback" | "unavailable";
     reason: string;
     passed: string[];
     ok: boolean;
@@ -44,8 +44,8 @@ interface PullRequest {
         };
     };
 }
-/** Verify required checks or the explicitly reported conservative fallback at the PR head. */
-export declare function checkCloseoutHead(api: CloseoutApi, repo: string, pr: PullRequest): Promise<CheckGate>;
+/** Verify metadata-backed or caller-declared requirements before considering observed head runs. */
+export declare function checkCloseoutHead(api: CloseoutApi, repo: string, pr: PullRequest, declared?: string[]): Promise<CheckGate>;
 /**
  * Whether a closing keyword directly precedes a link, given the line text before the link.
  *
@@ -68,8 +68,9 @@ export declare class CloseoutUsageError extends Error {
 /**
  * Describe the verified check evidence for a passed gate without overstating it.
  *
- * The required rule states that the required checks were satisfied and lists every successful head check (optional
- * ones included). The fallback rule (no readable required contexts)
+ * The required rule reports required-check success; the declared rule reports caller-declared success
+ * and unavailable repository metadata. Both list every successful head check (optional ones included).
+ * The fallback rule (fully readable metadata with no required contexts)
  * may pass on neutral or skipped runs alone, so it states that policy and lists successful checks only when any exist.
  */
 export declare function checkEvidence(gate: CheckGate): string;

package/dist/closeout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"closeout.d.ts","sourceRoot":"","sources":["../closeout.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"closeout.d.ts","sourceRoot":"","sources":["../closeout.ts"],"names":[],"mappings":"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"}