pm-github 2026.10.15 → 2026.10.19

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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
+
+- Add a reusable gated closeout PR workflow ([pm-github-0x3y](https://github.com/unbraind/pm-github/blob/main/.agents/pm/tasks/pm-github-0x3y.toon))
+- Let reusable sync choose its npm project directory ([pm-github-z5z1](https://github.com/unbraind/pm-github/blob/main/.agents/pm/features/pm-github-z5z1.toon))
+
+### Fixed
+
+- Refuse reusable sync runs outside the caller default branch ([pm-github-q4uz](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-q4uz.toon))
+
 ## 2026.10.15 - 2026-10-15
 
 ### 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,19 +67,34 @@ 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.
-
-TOON is the compact default; global `--json` returns the stable shape
-`{command, repo, dry_run, plan, checks, closed, failed}`. Each plan row is exactly
-`{item, pr, action: "close" | "skip", reason}`. `checks` reports each PR's rule,
-verdict, explanation and successful check names. Dry-run rows describe intended
+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,
+other_repository: 10, duplicate_selection: 5}`. Explicit exclusions use
+`explicit_skip`. Only checks for actionable rows are shown. Use `--full` for every
+plan row and selected PR check. Global `--json` always returns the full shape
+`{command, repo, dry_run, plan, checks, closed, failed}`. Each full plan row is
+`{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. `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
@@ -99,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
@@ -111,8 +131,8 @@ criteria remain the only prose source; PR body and comments supply no field text
 Completion time is the GitHub merge time. Repeating a completed selection skips
 terminal items and performs zero additional tracker writes. The command edits
 only the tracker; commit it with its history and regenerate the caller's
-changelog in a closeout PR. Reusable bot-branch automation is tracked separately
-in [pm-github-0x3y](https://github.com/unbraind/pm-github/blob/main/.agents/pm/tasks/pm-github-0x3y.toon).
+changelog in a closeout PR. The [automated closeout workflow](#automated-closeout-workflow)
+performs that daily review-PR preparation for fleet repositories.
 
 ## Revalidate GitHub blockers
 
@@ -444,8 +464,203 @@ 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` 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 workflow resolves the caller's default branch through the repository API,
+with event metadata as fallback, and refuses other run refs before checkout.
+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 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
+avoids losing deliveries during schedule outages; it costs more API reads for
+large repositories. Terminal items are skipped and the command retains its
+normal eligibility, child/epic, required-check and strict-close rules. Full
+closeout reports stay in runner scratch storage. The PR body lists
+actionable rows with item, PR number, action and code, plus skip counts by reason.
+This compact summary passes its own privacy scan before publication. The caller's `post-closeout-script` defaults to `changelog:full`,
+run through `npm run --if-present` in the npm project; empty disables it.
+The script must emit the root `CHANGELOG.md` and remain inside the publication scope.
+
+| Safety boundary | Closeout and sync parity |
+| --- | --- |
+| Entry and install | Caller default-branch guard, contained npm project, exact package version, SHA-pinned Actions, no persisted checkout credentials |
+| Proposed publication | SDK-resolved tracker plus root changelog; setup, extension, lock and checkpoint files excluded; every changed path checked |
+| Privacy | Same fail-closed full-context staged-diff scan after the caller script and immediately before commit; unreadable input refuses publication |
+| 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 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 `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
+`incomplete_merge` refusal before any head lookup. The pinned extension must
+emit plan decision codes; repin to a release containing this contract. A push/PR denial fails publication and
+CI dispatch denial fails the job explicitly. A PR creation denial may leave the
+gated bot branch pushed, and a dispatch denial leaves the review PR open; neither
+case changes the default branch or merges anything. Explicit dispatch is used
+for reliable caller CI invocation with `GITHUB_TOKEN`
+([GitHub token event behavior](https://docs.github.com/en/actions/concepts/security/github_token)).
+
 ## Automated sync workflow
 
+The reusable workflow's first step resolves the caller's default branch using the repository API with the job token, falling back to `github.event.repository.default_branch` only when present. Scheduled payloads need no `repository` object. If neither source provides a valid branch, the job fails closed with a clear error before checkout. It requires `github.ref` to equal `refs/heads/<resolved-default-branch>`. A mismatch fails before checkout or any sync operation with a one-line error naming both refs. Scheduled calls and manual `workflow_dispatch` calls on the default branch are accepted; manual dispatches selecting another branch are refused. Checkout, sync-branch preparation, PR lookup/base and tracker links all use that resolved branch, including defaults such as `trunk` or `release/stable`. Callers need no guard of their own. Repin the reusable workflow to a release commit containing this guard to receive it.
+
 Fleet repos sync their issues into pm through ONE audited implementation: the reusable `workflow_call` workflow at [`.github/workflows/pm-github-sync.yml`](.github/workflows/pm-github-sync.yml). Its safety order is validate → dry-run plan → **gated import** → verify the repeat import is a no-op → caller post-import script → **full changed-path scope check and privacy gate** → strict health → repeat scope check and scan immediately before commit/push/review PR → caller CI dispatch. The default `post-import-script` is `changelog:full`, invoked with `npm run --if-present`: it runs the caller's own generator when present, so imported closed issues and their changelog entries land in the same commit. Actions are pinned by commit SHA. The job requests `contents: write`, `pull-requests: write`, `issues: read`, and `actions: write` for dispatch.
 
 When the tracker has no changes, regenerated `CHANGELOG.md` drift is discarded and the run emits a notice that the caller's own `changelog:check` owns that drift. The sync closes any owned open review PR and exits successfully without pushing or dispatching CI. Changelog changes are published only together with tracker changes.
@@ -461,10 +676,12 @@ Optional inputs:
 
 | Input | Default | Behavior |
 | --- | --- | --- |
+| `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
@@ -481,14 +698,31 @@ 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 calling repo needs `@unbrained/pm-cli` as a devDependency (the workflow's `npm ci` provides the CLI) and its pm tracker at `.agents/pm` committed on `main`. 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.
-
-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).
+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`
+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 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
 
@@ -547,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

@@ -13,11 +13,15 @@ export interface CloseoutRow {
     pr: number;
     action: "close" | "skip";
     reason: string;
+    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" | "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;
-    rule: "required" | "fallback" | "unavailable";
+    code: CloseoutCode;
+    rule: "required" | "declared" | "fallback" | "unavailable";
     reason: string;
     passed: string[];
     ok: boolean;
@@ -40,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.
  *
@@ -64,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;
@@ -79,5 +84,22 @@ export declare function runCloseout(pmRoot: string, repo: string | undefined, op
     closed: number;
     failed: number;
 }>;
+/** Keep actionable decisions and their checks while counting routine skips by stable code. */
+export declare function compactCloseoutReport(report: Awaited<ReturnType<typeof runCloseout>>): {
+    command: string;
+    repo: string;
+    dry_run: boolean;
+    closed: number;
+    failed: number;
+    plan: {
+        item: string;
+        pr: number;
+        reason: string;
+        code: CloseoutCode;
+        action: string;
+    }[];
+    skipped: Partial<Record<CloseoutCode, number>>;
+    checks: CheckGate[];
+};
 export {};
 //# sourceMappingURL=closeout.d.ts.map

package/dist/closeout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"closeout.d.ts","sourceRoot":"","sources":["../closeout.ts"],"names":[],"mappings":"AAGA,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,UAAU,SAAS;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,iFAAiF;AACjF,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CACpD;AA8ID,8FAA8F;AAC9F,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CA6C3G;AAQD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAuBxD;AAED,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EAAE,CAuBtG;AAQD,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAO5D;AAED,sHAAsH;AACtH,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAOhD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAKrD;AAED,gFAAgF;AAChF,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW;;;;;;;;GAuF7H"}
+{"version":3,"file":"closeout.d.ts","sourceRoot":"","sources":["../closeout.ts"],"names":[],"mappings":"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"}