@unbrained/pm-cli 2026.9.23 → 2026.9.25

package/docs/AGENT_RECOVERY_AND_GUIDANCE.md

@@ -0,0 +1,49 @@
+# Agent Recovery and Guidance
+
+Tracked by [pm-o5s22y](../.agents/pm/issues/pm-o5s22y.toon) and
+[pm-80k965](../.agents/pm/issues/pm-80k965.toon).
+
+## Policy refusals preserve context
+
+A workflow `require_fields` refusal names the missing metadata and the policy
+that requires it. SDK `PmCliError.context` carries `policy_violations`, the
+full refusal count, policy descriptions, and missing-field recovery. CLI JSON
+adds that same evidence to `refusal.policies` and `refusal.missing_fields`.
+Its `surface` identifies `policy:<id>` rather than attributing the failure to
+an unrelated, valid flag such as `--resolution`.
+
+Diagnostics show at most three policy rows and disclose the total. The complete
+policy remains available through `pm schema policies`. Recovery maps metadata
+to declared update flags; package-defined fields retain their SDK/package
+contract instead of receiving an invented CLI option. For example, a missing
+`actual_result` produces an update using `--actual-result`, followed by a retry
+of the refused operation. Refusals preserve item state and record the policy
+refusal in workspace history. Creation and import refusals instead direct the
+caller to supply evidence in the original request, because no item was created.
+Generated update commands include a shell-quoted `--pm-path` to retain the
+refusing tracker even when an SDK caller works outside that project.
+
+See [Declarative Workflow Policies](WORKFLOW_POLICIES.md) for portable policy
+declarations and approval semantics.
+
+## Refresh managed agent instructions
+
+Root and alias help examples use canonical commands. Help for a deprecated
+alias explicitly identifies its replacement. Generated instructions use
+`pm claim <id> --start` to claim and start work atomically.
+
+`pm init --agent-guidance status` compares existing managed blocks with the
+current template. `pm health --summary` reports `agent_guidance_outdated` as an
+advisory and supplies this repair command:
+
+```bash
+pm init --agent-guidance add
+```
+
+The repair refreshes stale managed blocks in both `AGENTS.md` and `CLAUDE.md`,
+preserves all surrounding user instructions, and becomes a no-op after the
+first successful refresh. It does not replace handwritten guidance without
+managed markers. Status and health inspection do not rewrite these files.
+An unreadable guidance path produces an `agent_guidance_unreadable` advisory;
+health still reports the remaining checks and suggests inspecting file types
+and read permissions.

package/docs/CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md

@@ -6,6 +6,8 @@ Tracked research: [pm-n28t](../.agents/pm/tasks/pm-n28t.toon). Future implementa
 Research date: **2026-07-11**. This page is a research and implementation plan. It does not record a completed
 plugin remediation, ChatGPT app deployment, or public plugin submission.
 
+Update for [pm-95d7](../.agents/pm/features/pm-95d7.toon): the Claude and Codex cached launchers now resolve a runtime pinned to the plugin version and reuse it offline after first installation. The remaining sections preserve the July research baseline and the separate ChatGPT app/public distribution plan; historical `@latest` findings below describe the pre-remediation state.
+
 ## Executive Conclusion
 
 The current `plugins/pm-codex` package is an actual native Codex plugin, but it is not yet a complete,

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -24,7 +24,9 @@ pm-cli/ (repo root)
 │   │   └── session-start.mjs # Injects pm context at session start
 │   ├── agents/              # Subagent definitions (one .md per coordinator/triage/verification subagent)
 │   ├── scripts/
-│   │   └── pm-mcp-server.mjs # MCP server launcher (repo → npx fallback)
+│   │   ├── pm-mcp-server.mjs # MCP server launcher
+│   │   └── plugin-runtime.mjs # Exact-version runtime resolver
+│   ├── package.json         # Pinned pm-cli dependency
 │   └── README.md            # User-facing installation guide
 └── scripts/
     └── smoke-claude-plugin.mjs  # Full plugin smoke test (run in CI)
@@ -83,10 +85,10 @@ agent mutations do not need a hard-wired `PM_AUTHOR`.
 `plugins/pm-claude/scripts/pm-mcp-server.mjs` resolves the server in order:
 
 1. `PM_CLI_MCP_SERVER` env var (explicit override)
-2. `dist/mcp/server.js` walking up from the launcher (repo checkout)
-3. `npx -y --package=@unbrained/pm-cli@latest pm-mcp` (npm-installed fallback)
+2. `dist/mcp/server.js` at the matching repository root, when the checkout package and plugin versions agree
+3. The exact `@unbrained/pm-cli` version declared in the plugin's `package.json`, installed under the plugin data directory on first use
 
-This means the plugin works both from a repo checkout and from an npm-cached plugin install.
+The cached runtime is reused offline. It never resolves npm's moving `latest` tag. A first install needs npm access; an unavailable pinned release causes an explicit startup failure.
 
 ## Session Start Hook
 
@@ -94,7 +96,7 @@ This means the plugin works both from a repo checkout and from an npm-cached plu
 
 1. Checks for `.agents/pm/settings.json` in the current workspace.
 2. Exits silently if pm is not initialized.
-3. Runs `pm context --limit 5 --json` with a 5-second timeout.
+3. Runs `pm context --limit 5 --json` from the same pinned runtime as the MCP server, with a 15-second command timeout.
 4. Injects a compact status line into the session context.
 
 Example injection:
@@ -121,6 +123,15 @@ discovery for `2026-07-28`, 32 tools present, full workflow (init → create →
 claim → update → link files/docs/tests → get → context → search → validate →
 health), and session-start hook.
 
+The copied-cache smoke packs the current build, installs it under a temporary
+plugin data directory, copies both plugin bundles away from the checkout, and
+restarts their MCP launchers with npm unavailable:
+
+```bash
+pnpm build
+pnpm smoke:plugin-cache
+```
+
 ### MCP server smoke test
 
 ```bash
@@ -182,9 +193,9 @@ After installing the plugin:
 
 | pm-cli version | Plugin version | Claude Code version |
 |---------------|----------------|---------------------|
-| 2026.5.x+ | 1.x | Any current |
+| Exact same date-based version as the plugin | Exact same date-based version as pm-cli | Current supported Claude Code |
 
-The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.json`; this row stays on the `1.x` major line so it does not drift with each plugin release.
+The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.json`; `pnpm version:check` also verifies the pinned runtime dependency.
 
 The MCP server uses JSON-RPC 2.0 over stdio with canonical protocol version
 `2026-07-28`. A bounded legacy path remains for unversioned older hosts, with

package/docs/CODEX_PLUGIN.md

@@ -3,7 +3,7 @@
 pm-cli ships a repo-local Codex plugin at [`plugins/pm-codex`](../plugins/pm-codex/README.md).
 
 It is a real Codex plugin package: the repo marketplace installs it and Codex registers its skills and bundled
-MCP server. It is not yet a self-contained cached runtime or an Apps SDK-backed ChatGPT app. The official-source
+MCP server. Its cached runtime installs the exact version declared by the plugin manifest and works offline after that first install. It is not yet an Apps SDK-backed ChatGPT app. The official-source
 audit, verified gaps, and phased remediation plan are documented in
 [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md).
 
@@ -25,19 +25,12 @@ Keep this page as the public docs router so the MCP tool/action list has one mai
 
 ## Current MCP Runtime Note
 
-The plugin launcher uses the local repository build when `dist/mcp/server.js` is present. When the plugin is cached outside the repo, it falls back to:
-
-```bash
-npx -y --package=@unbrained/pm-cli@latest pm-mcp
-```
-
-The fallback starts the package MCP server, not the `pm` CLI command. Tool calls import pm command modules and return JSON-compatible structured results.
-
-This is current behavior, not the target distribution contract. A normal cached install has no repository
-`dist/` ancestor, so it depends on npm availability and can run a newer server than the installed plugin. Track
-the self-contained, version-coherent runtime work under
+The plugin launcher uses the local repository build when `dist/mcp/server.js` is present. A copied plugin installs the exact `@unbrained/pm-cli` version in its `package.json` to persistent plugin data, then starts its `pm-mcp` server directly with Node. The installed runtime can be reused offline. Track the remaining native-plugin and ChatGPT app work under
 [pm-95d7](../.agents/pm/features/pm-95d7.toon).
 
+Run `pnpm build && pnpm smoke:plugin-cache` to verify both copied plugin
+bundles against a real packed install with npm unavailable at MCP startup.
+
 ## Safety
 
 For real repository tracking, leave `path` unset so pm uses the repository `.agents/pm` root. For tests, use a sandbox `cwd` or `path` and isolate `PM_GLOBAL_PATH`.

package/docs/DEFECT_RECURRENCE.md

@@ -1,6 +1,6 @@
 # Defect Recurrence and Boundary Evidence
 
-Tracked by [pm-1qkivy](../.agents/pm/features/pm-1qkivy.toon), [pm-rtn5h6](../.agents/pm/tasks/pm-rtn5h6.toon), [pm-0pzgit](../.agents/pm/tasks/pm-0pzgit.toon), [pm-7c27ep](../.agents/pm/issues/pm-7c27ep.toon), and [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon).
+Tracked by [pm-1qkivy](../.agents/pm/features/pm-1qkivy.toon), [pm-rtn5h6](../.agents/pm/tasks/pm-rtn5h6.toon), [pm-0pzgit](../.agents/pm/tasks/pm-0pzgit.toon), [pm-7c27ep](../.agents/pm/issues/pm-7c27ep.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), and [pm-003j](../.agents/pm/tasks/pm-003j.toon).
 
 ## Agent Quick Context
 
@@ -192,6 +192,13 @@ adds a disconnected, unregistered recurrence pair and must also exit `1`. Focuse
 
 `repository-defect-evidence-required` is part of the blocking `repository-static-quality` assurance composition. That makes local and CI behavior share the same provider result, assertion negative control, enforcement, and immutable verdict semantics.
 
+The static quality pipeline also runs `node scripts/check-workflow-permissions.mjs`.
+It parses every GitHub workflow and requires an explicit read-only default token;
+write scopes belong on jobs that use them. Run its `--negative-control` mode to
+confirm a workflow-scope `contents: write` grant exits with status 1. This
+protects the least-privilege workflow policy that [pm-003j](../.agents/pm/tasks/pm-003j.toon)
+tracks, even between Scorecard scans.
+
 The mandatory `gate-registry` check also compares each recurrence family's `checks.hosted` values with concrete names derived from the repository workflows. It expands static matrix axes and applies exclusions before inclusions according to [GitHub's matrix rules](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrixinclude). Renamed or removed checks produce named findings. Runtime expressions, unnamed matrix jobs, and static expansions beyond 256 combinations cannot certify a required check name. The public SDK policy parser remains provider-neutral; this workflow binding belongs to the repository gate.
 
 Assurance request schemas declare each family's required identity, triggers,

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -78,3 +78,30 @@ Readiness, `pm next`, context blocker summaries, `pm list-blocked`, downstream `
 `pm deps` returns `legacy_alias_counts` for the workspace. `pm graph audit` returns the same field beside canonical `profile.edges_by_kind` counts, `profile.edge_share_by_kind` composition ratios, and the `semantic_edges`/`semantic_edge_share` context-preservation census. The semantic census counts `discovered_from`, `incident_from`, `recurs_from`, `supersedes`, and `verifies` over all deduplicated directed edges. Empty objects and zero shares are explicit, not omitted. These diagnostics are read-only; terminal history remains untouched until an explicitly governed migration is requested.
 
 Assurance `dependency_kind` measurements canonicalize both the declaration and stored row before comparing. A declaration using `related` and one using the accepted `related_to` alias therefore measure the same edge population; alias debt remains separately observable through `legacy_alias_counts`.
+
+## Composition policy when adding relationships
+
+Tracked by [pm-r3o7x4](../.agents/pm/issues/pm-r3o7x4.toon).
+
+Choose the kind that states the actual relationship. Use `related` for honest
+association; never relabel it as evidence or ordering merely to pass a gate.
+This workspace enforces `profile.semantic_edge_share` over canonical,
+deduplicated directed edges in both graph-composition and tracker-context-quality.
+The raw association count and declared-row share remain diagnostics. Neither
+imposes a second blocking bound on otherwise healthy graph growth.
+
+Adding a provenance or verification edge cannot lower that composition ratio.
+Adding only association, hierarchy, implementation, or ordering edges can lower
+it; a mixed addition that increases semantic share passes the composition floor
+whenever its baseline passed. Ordering and hierarchy still have their own
+integrity constraints. Inspect the active workspace policy before bulk changes:
+
+```bash
+pm assurance show gate graph-composition
+pm assurance show assertion graph-semantic-edge-share-floor
+pm assurance run graph-composition --trigger ci --dry-run
+```
+
+The floor is a declared minimum, not a promise that every small dilution fails.
+Real growth is allowed above it; an associative-only pass crossing the floor is
+refused. Both terminal and active history contribute to the same denominator.

package/docs/MERGE_SAFETY.md

@@ -51,12 +51,13 @@ shell quoting when it expands the placeholder. Receipt ingestion also removes
 one legacy matching quote pair so receipts written by older clone-local drivers
 remain reconcilable.
 `pm validate --check-storage-integrity` and `pm health` also compare every
-clone-local driver definition with the installed SDK. Exact commands remain the
-fast path. A command installed by another valid `@unbrained/pm-cli` package is
+effective driver definition with the installed SDK. A command installed by
+another valid `@unbrained/pm-cli` package is
 also accepted when its Node and `dist/cli.js` paths exist, its manifest owns the
-`pm` bin, and the driver arguments are semantically identical. This keeps
-copied worktrees and upgraded global installs healthy without accepting an
-arbitrary executable. A missing, malformed, or semantically stale definition is
+`pm` bin, the driver arguments are semantically identical, and its version
+matches any exact project runtime pins. A driver inside a sibling worktree of
+the same repository is rejected, even when that package is otherwise valid.
+Independent global installations remain supported. A missing, malformed, or semantically stale definition is
 reported even when the committed attribute fence is correct.
 Health and validation name `pm merge install` as the repair command for missing
 or drifted drivers. This upgrade behavior is tracked by
@@ -64,6 +65,28 @@ or drifted drivers. This upgrade behavior is tracked by
 
 The installer publishes the shared `.gitattributes` fence only after the clone-local driver commands are configured. If the repository Git config is read-only or another Git process holds its lock, the command returns the stable `merge_git_config_unwritable` error with recovery guidance and leaves an absent fence absent. Use `pm merge install --dry-run --json` to inspect the contract in intentionally read-only workspaces.
 
+### Independent worktree runtimes
+
+Tracked by [pm-c1dwbt](../.agents/pm/issues/pm-c1dwbt.toon).
+
+Run `pm merge install` from each worktree with that worktree's intended pm
+installation. When installing in a linked worktree, the SDK enables Git's
+`extensions.worktreeConfig` and writes drivers with `git config --worktree`.
+Existing main-worktree drivers are preserved in its `config.worktree`; later
+installs cannot replace another worktree's runtime. Main-only `core.worktree`
+and `core.bare=true` settings migrate with their original scope. Ordinary
+clones retain local configuration until worktree isolation is needed.
+Git subprocesses discard inherited repository-location variables so an SDK
+caller's `GIT_DIR` cannot redirect installation or diagnosis to another clone.
+Configuration migration uses multiple Git writes: a failed write is reported,
+and rerunning `pm merge install` after resolving the config lock or permissions
+completes the migration while preserving values already copied for the main tree.
+
+Health reads Git's effective configuration, including worktree overrides.
+Removing a sibling worktree does not remove a separately installed main driver.
+Use `pm merge install` in the affected worktree to repair stale, missing, or
+incompatible commands. A dry run changes neither configuration nor attributes.
+
 ### Fence coverage contract
 
 The fenced block is generated by one shared coverage contract (`buildMergeAttributePatterns`) covering every mergeable artifact class: tracker-wide `**/*.toon` and `**/*.md` item patterns, explicit per-type diagnostic patterns, all tracker `**/*.jsonl` paths under the relationship-event driver with the more-specific `history/*.jsonl` rule overriding history streams, root `settings.json`, and every nested `**/*.json` document. The tracker-wide item rules protect extension-defined type folders even when a receiving branch has not installed the package that registered them; explicit type rows still make active-registry drift diagnosable. The broad JSON rules automatically cover schema, managed-extension, evaluation-corpus, and future package-owned authoritative JSON without another hand-maintained allowlist. The broad JSONL rule is required because `RelationshipEventStore` supports package-owned custom relative paths anywhere below the tracker root. Two mechanisms keep the committed fence from drifting out of that contract:

package/docs/README.md

@@ -68,6 +68,7 @@ pm guide release --json
 - [History Algorithms and Detached Attestations](HISTORY_ATTESTATION.md) - named record digests, portable exact-byte proofs, and read-only verification.
 - [History-derived Governance Repair](HISTORY_GOVERNANCE_REPAIR.md) - verified closure timestamps and typed issue-code lineage.
 - [History Maintenance and Recovery](HISTORY_MAINTENANCE.md) - native history commands, permanent aliases, shared SDK transforms, and transactional recovery.
+- [Agent Recovery and Guidance](AGENT_RECOVERY_AND_GUIDANCE.md) - policy refusal evidence, canonical help, and managed instruction freshness.
 - [Declarative Workflow Policies](WORKFLOW_POLICIES.md) - portable lifecycle requirements, independent approvals, and completeness reports.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.

package/docs/RELEASE_RELIABILITY.md

@@ -0,0 +1,70 @@
+# Scheduled release reliability
+
+Tracked by [pm-e70zh5](../.agents/pm/issues/pm-e70zh5.toon) and
+[pm-44u3wt](../.agents/pm/issues/pm-44u3wt.toon).
+
+The **Release Reliability** workflow evaluates the preceding 30 days after a
+scheduled Auto Release completes, daily at nominal 04:35 UTC, and on manual
+dispatch. It saves a JSON report and fails its own check when policy is breached.
+The report is independent of candidate correctness: historical failures must
+remain visible while a reviewed repair can still pass publication gates.
+
+## Policy and clock
+
+[The versioned policy](../config/release-reliability-policy.json) declares the
+nominal release cron as 02:35 UTC, a 60-minute dispatch allowance, a maximum
+10% failure rate, and at least seven completed observations. These are explicit
+operational targets, not thresholds fitted to make the current history green.
+Missing samples yield an insufficient-data failure, never a healthy zero rate.
+
+Dispatch delay measures `created_at` against the nearest preceding nominal
+daily occurrence. Queue delay separately measures `run_started_at - created_at`.
+GitHub does not supply the intended scheduled timestamp: the inferred occurrence
+cannot disambiguate delays greater than 24 hours. Missing the latest occurrence
+whose 60-minute allowance has elapsed produces `missing_scheduled_run`. Before
+03:35 UTC, absence of today's run is still within the allowance; afterward,
+inspect the report to distinguish missing dispatch, a pending attempt, and a
+completed failure. A late run is visible even when it subsequently succeeds.
+
+The release version and one-per-day guard use the UTC execution date captured
+by release preparation, not the inferred cron occurrence. A delayed run cannot
+backdate a tag. Reporting never creates, retargets, retries, or publishes a tag.
+The unchanged [release recovery rules](RELEASING.md#failure-handling) apply.
+
+## Evidence and denominator
+
+The collector paginates the schedule-only runs API over an explicit half-open
+UTC window and checks returned counts and unique IDs. It retrieves attempt 1
+when a run was rerun. A later successful attempt, manual dispatch, issue recovery,
+or closed blocker cannot change the original scheduled failure. Pending runs
+are listed separately; all completed non-success conclusions count as failures.
+API errors, truncated pages, ambiguous artifacts, and mismatched run identities
+fail collection rather than silently reducing the denominator.
+
+Auto Release saves `release-observation-<attempt>` artifacts for 90 days. Each
+contains only run/attempt identity, event, outcome and failure-stage name. Gate
+stdout, stderr, credentials and environment values are not archived. A confirmed
+publication, verified existing same-day release, unchanged source, tracker-only
+changes, and an empty changelog are distinct outcomes. Failed gates retain their
+structured stage; older failures fall back to failed job/step names from GitHub.
+Receipt writing and upload are non-blocking so an evidence-service outage cannot
+change publication success into a release blocker. Missing or expired success
+receipts are `unknown_success`, with
+`outcome_evidence_complete: false`; success alone does not prove publication.
+
+Reports retain the input policy, window, per-run observations, outcome counts,
+stage counts, denominator, failure rate and violations. Download a report using
+`gh run download <report-run-id> --name <artifact-name> --dir <temporary-directory>`.
+The pure evaluator in `scripts/release/release-reliability.mjs` permits offline
+replay with a fixed clock and captured input; the collector is read-only and
+downloads only data, never executable source. The reporting workflow checks out
+the default branch rather than the triggering run's code and has read-only token
+permissions.
+
+The report is a rolling observation, not a permanent archive of all releases.
+Retain exported receipts externally if a longer historical window is needed.
+It does not implement the separate nightly per-leg reliability programme or
+change the manual same-day version policy.
+
+Provider contracts: [workflow run attempts](https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run-attempt)
+and [completion-triggered workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_run).

package/docs/RELEASING.md

@@ -447,6 +447,10 @@ gh run watch <run-id> --exit-status
 
 ## Post-Release Verification
 
+Use the [rolling reliability report](RELEASE_RELIABILITY.md) as well as the
+latest release result. Its first-attempt denominator, explicit outcome receipts,
+and UTC dispatch policy preserve failures even after a recovery succeeds.
+
 ```bash
 npm view @unbrained/pm-cli@<version> version dist.integrity dist.unpackedSize --json
 npx --yes --package @unbrained/pm-cli@<version> -- pm --json --no-extensions contracts --summary

package/docs/TESTING.md

@@ -88,6 +88,23 @@ so PR-local CodeFactor maintainability annotations fail locally before commit or
 push. Existing legacy high-complexity test fixtures are tracked separately and
 must not be used as precedent for new changed production/script code.
 
+The same required static gate validates an explicit seven-day Dependabot
+cooldown for every updater and requires both npm and GitHub Actions entries.
+Missing values, semver overrides outside 7–90 days, invalid YAML, removed
+updaters, and include/exclude bypasses fail the gate. The maximum follows
+[GitHub's cooldown limits](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/optimizing-pr-creation-version-updates).
+Security updates retain GitHub's separate security-update behavior.
+The negative controls are tracked by [pm-gkut](../.agents/pm/issues/pm-gkut.toon)
+and [pm-dmo5](../.agents/pm/issues/pm-dmo5.toon).
+
+Release synchronization and commit staging share one distribution manifest
+inventory. The [pm-t4prek regression](../tests/unit/scripts/release/version-manifests.spec.ts)
+bumps versions in a temporary Git repository and reads the resulting commit to
+verify workspace versions and exact plugin runtime pins. The pipeline checks
+version consistency immediately before staging, including required string
+versions and runtime pins in both plugin package manifests; tests of a prepared working
+tree alone cannot establish that the release commit contains those changes.
+
 `lint:duplicates` runs three zero-clone profiles: the broad repository profile,
 the production cross-format profile, and a supplemental long-table profile at
 28 lines / 80 tokens. The last profile detects the historical GH-508 normalizer

package/docs/VALIDATION_PORTABILITY.md

@@ -1,7 +1,8 @@
 # Completion portability and bounded replication checks
 
-Tracked by [pm-t6jl1f](../.agents/pm/issues/pm-t6jl1f.toon) and
-[pm-26y269](../.agents/pm/tasks/pm-26y269.toon).
+Tracked by [pm-t6jl1f](../.agents/pm/issues/pm-t6jl1f.toon),
+[pm-26y269](../.agents/pm/tasks/pm-26y269.toon), and
+[pm-eswzn9](../.agents/pm/tasks/pm-eswzn9.toon).
 
 ## Bash completion data boundary
 
@@ -13,10 +14,15 @@ elements to `COMPREPLY`. Candidates containing shell metacharacters or Unicode
 use portable single-quote syntax, including embedded quote escaping, so accepting
 a candidate and pressing Enter also preserves its literal argument value.
 
-Already quoted or backslash-escaped prefixes return no suggestions before optional
-completion initialization can remove their quoting. This conservative boundary
-avoids inserting an unquoted-context escape inside a different shell quoting
-context. Normal unquoted prefixes retain literal matching.
+The matcher decodes the current Readline word without evaluation. It recognizes
+open single quotes, open double quotes, and backslash-escaped prefixes. Each
+completion is encoded for its insertion context: apostrophes are split safely
+inside single quotes; dollar signs, backticks, backslashes, and double quotes
+are escaped inside double quotes; exclamation marks use a single-quoted segment
+so history expansion cannot change the accepted bytes. Unquoted prefixes keep
+the existing literal single-quote encoding for unsafe candidates. Mixed quoted
+segments whose replacement span is ambiguous, and prefixes containing typed
+backticks, still return no suggestions.
 
 The matcher never evaluates choices as shell programs. Dollar signs, backticks,
 quotes, backslashes, and wildcard characters remain literal. Unicode survives
@@ -37,9 +43,10 @@ and cache policy retain their existing contracts.
 `compgen -W` cannot safely serve as the data transport here: it performs another
 expansion pass, and Bash 3.2 does not round-trip the ANSI-C quoting emitted by
 `printf %q` for Unicode. Unquoted command-substitution arrays can additionally
-expand literal wildcard candidates into filenames. The regression executes the
-generated function and parses its accepted words with the real Bash parser,
-rather than inferring safety from source substrings.
+expand literal wildcard candidates into filenames. The regression checks the
+generated function and uses an interactive pseudo terminal to press Tab and
+Enter in each supported insertion context. It checks the accepted argument
+bytes and verifies that a command-substitution sentinel was not created.
 
 Run the focused native regression after building:
 
@@ -51,8 +58,10 @@ To test another installed Bash version, set `PM_COMPLETION_TEST_BASH` to its
 executable path. This is a test harness input, not a CLI configuration setting.
 The existing macOS runtime-smoke job pins `/bin/bash` so PATH cannot silently
 substitute a newer Homebrew Bash. It runs this regression before merge; Linux
-coverage runs the same matrix. Native Fish and Zsh acceptance remains in the
-required smoke gate.
+coverage runs the same matrix. The macOS test drives Bash through a Python 3
+pseudo terminal because BSD `script` requires terminal stdin; Linux uses
+`script`. Set `PM_COMPLETION_TEST_PTY=python` to exercise the macOS driver on
+Linux. Native Fish and Zsh acceptance remains in the required smoke gate.
 
 ## Replication diff collection
 

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.9.23"
+    "version": "2026.9.25"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.9.23",
+      "version": "2026.9.25",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -123,7 +123,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json && jscpd --config .jscpd.source.json && jscpd --config .jscpd.tables.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm quality:docstrings && pnpm quality:exports && pnpm lint:eslint && pnpm lint:duplicates && pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded && pnpm quality:mutation -- --prebuilt",
+    "quality:static": "pnpm quality:docstrings && pnpm quality:exports && pnpm lint:eslint && pnpm lint:duplicates && node scripts/check-workflow-permissions.mjs && node scripts/check-dependency-cooldown.mjs && node scripts/gen-plugin-mcp-wrappers.mjs --check && pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded && pnpm quality:mutation -- --prebuilt",
     "quality:exports": "knip --no-config-hints && node scripts/run-tests.mjs test -- tests/unit/scripts/release/dead-exports.spec.ts",
     "quality:command-grammar": "pnpm build && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs",
     "quality:recovery-closure": "pnpm build && node scripts/release/refusal-closure-gate.mjs",
@@ -167,6 +167,7 @@
     "smoke:external-packages": "node scripts/smoke-external-packages.mjs",
     "smoke:codex-plugin": "node scripts/smoke-codex-plugin-mcp.mjs",
     "smoke:claude-plugin": "node scripts/smoke-claude-plugin.mjs",
+    "smoke:plugin-cache": "node tests/acceptance/plugin-cache-smoke.mjs",
     "version:check": "node scripts/release-version.mjs check && node scripts/sync-versions.mjs check",
     "version:next": "node scripts/release-version.mjs next",
     "version:sync": "node scripts/sync-versions.mjs apply",
@@ -211,7 +212,7 @@
     "node": ">=22.18.0"
   },
   "dependencies": {
-    "@sentry/node": "10.75.0",
+    "@sentry/node": "10.75.1",
     "@toon-format/toon": "^4.1.1",
     "@types/node": ">=22",
     "commander": "^15.0.0",
@@ -238,13 +239,13 @@
     "fast-check": "^4.10.2",
     "github-slugger": "2.0.0",
     "greptile": "^3.5.3",
-    "jscpd": "^5.3.0",
+    "jscpd": "^5.3.1",
     "knip": "^6.37.0",
     "marked": "18.0.13",
     "parse5": "8.0.1",
     "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.70.0",
+    "typescript-eslint": "^8.70.1",
     "vitest": "^4.1.11"
   }
 }

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.9.23",
+  "version": "2026.9.25",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",