@unbrained/pm-cli 2026.9.23 → 2026.9.26

package/.agents/skills/README.md

@@ -24,6 +24,7 @@ it. `docs/COMMANDS.md` is ~29k tokens and `docs/SDK.md` is ~45k.
 | Skill                             | Use when                                              |
 | --------------------------------- | ------------------------------------------------------ |
 | [`pm-developer`](pm-developer/SKILL.md) | Changing code, docs, tests, or release gates      |
+| [`pm-test-audit`](pm-test-audit/SKILL.md) | Writing, reviewing, or auditing tests and their regression value |
 | [`pm-user`](pm-user/SKILL.md)     | Intake, triage, prioritization, planning, reporting    |
 | [`pm-extensions`](pm-extensions/SKILL.md) | Package and extension lifecycle and authoring  |
 | [`pm-sdk`](pm-sdk/SKILL.md)       | Integrations, embedding, and domain packs on the SDK   |

package/.agents/skills/pm-developer/SKILL.md

@@ -106,6 +106,9 @@ Always read the `omission_receipt` before treating a result as complete. See
 
 ## Verification Defaults
 
+For test authoring, review, or cleanup, apply [pm-test-audit](../pm-test-audit/SKILL.md)
+to preserve independent contracts while removing low-value duplication.
+
 ```bash
 pnpm build
 node scripts/run-tests.mjs test -- <targets>

package/.agents/skills/pm-test-audit/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/.agents/skills/pm-test-audit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: pm-test-audit
+description: Use when writing, changing, reviewing, or auditing pm-cli tests. Checks regression value, duplicate coverage, implementation coupling, and test-only production seams while preserving SDK contracts, sandbox isolation, and exact coverage gates.
+license: MIT
+compatibility: Repository development with Node.js, pnpm, and the checkout-built pm CLI.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: test-quality
+---
+
+# pm Test Audit
+
+Tracker: [pm-xvibt6](../../pm/tasks/pm-xvibt6.toon).
+Adapted from OpenClaw's [test-audit skill](https://github.com/openclaw/openclaw/blob/e0d80000067d224e93af6107ed093a21e046879f/.agents/skills/test-audit/SKILL.md);
+upstream copyright and terms are in [LICENSE.txt](LICENSE.txt).
+
+Use alongside [pm-developer](../pm-developer/SKILL.md). Project management is
+context management: retain why a test exists, its contract owner, and the
+regression evidence so the next audit need not rediscover them.
+
+## Choose the Scope
+
+- **Authoring:** apply the four questions below before adding or changing tests.
+- **Audit:** read [audit evidence](references/AUDIT.md) before proposing removals.
+- **Campaign:** also read [campaign procedure](references/CAMPAIGN.md) for a broad sweep.
+
+Do not expand a focused request into a repository-wide deletion campaign.
+
+## Four Questions Before Editing
+
+1. What observable behavior, invariant, or independent contract does this prove?
+2. What credible regression makes it fail? For a bug fix, demonstrate the intended
+   failure before the fix and success afterward with the same test and harness.
+3. Why does existing coverage not catch it? Choose one primary owner at the
+   strongest useful boundary. An additional layer needs a distinct risk, such as
+   CLI parsing, MCP transport, persistence, or package installation. Extend a
+   table or shared fixture when the behavior and setup are already covered.
+4. Does it demand a production export, flag, wrapper, or injection hook solely
+   to observe private details? Prefer exercising the real boundary. Published
+   `@unbrained/pm-cli/sdk/testing` helpers are public contracts, not automatically
+   disposable test-only seams.
+
+Domain semantics belong in the SDK; thin CLI/MCP adapters need their own transport
+proof, not copies of every SDK case. Read complete tests and production owners
+before editing, plus relevant callers, neighboring tests, history, and scoped
+`AGENTS.md`. Inspect actual dependency types in `node_modules`; do not guess APIs.
+
+## Verification and Safety
+
+Follow [Testing](../../../docs/TESTING.md) for the affected surface. Use the
+repository runner, which isolates tracker roots and builds the checkout:
+
+```bash
+node scripts/run-tests.mjs test -- <target>
+node scripts/run-tests.mjs coverage
+```
+
+- Never run tests against the real `.agents/pm`. Manual dogfood uses a temporary
+  workspace outside this checkout and its ancestor workspaces, with both
+  `PM_PATH` and `PM_GLOBAL_PATH` isolated. Clean up only directories you created.
+- Do not edit source while a runner or build owns it. Negative controls and
+  pre-fix comparisons belong in an isolated copy/worktree with temporary
+  `PM_PATH` and `PM_GLOBAL_PATH` set for every direct stateful CLI command,
+  including linked-test metadata commands. A nested worktree alone does not
+  isolate tracker discovery. Keep these test roots separate from intentional
+  repository tracking below. Change the intended condition; unrelated setup
+  failures do not establish regression sensitivity.
+- Keep canonical full-source coverage at **100/100/100/100**. Do not shrink the
+  denominator, add ignore directives, lower gates, or duplicate assertions to
+  recover a number. Restore meaningful behavioral proof when coverage drops.
+- Mocks may isolate external boundaries; they must not implement the behavior
+  being tested. Use real temporary persistence when proving writes or recovery.
+- Run relevant functional, integration, package, performance, and acceptance
+  gates according to the changed contract. A focused green run is not a full
+  suite result. [Quality evidence](../../../docs/QUALITY_EVIDENCE.md) defines the
+  bounded mutation gate; do not describe it as whole-repository mutation proof.
+- Preserve static quality, docstring, security, release, and public-surface gates.
+  This skill does not grant exceptions to repository coding rules.
+
+## PM Evidence and Handoff
+
+Bootstrap and orient using root `AGENTS.md`; search all statuses before creating
+work. Read the selected item's full metadata and history, follow omission
+receipts, then claim/start only items actually being edited. Keep investigation
+read-only until there is a justified change. Use typed relationships for real
+ownership, dependencies, or verification; never manufacture graph depth.
+
+Link files, docs, and sandbox-safe test commands through `pm`. Record retained
+contracts, removed duplication, pre-fix failure and post-fix proof, commands and
+results, and limitations. Reuse canonical follow-up items for product defects;
+never delete a failing regression merely to make the suite green. Close with
+structured evidence and release the claim, or return paused work to an appropriate
+non-active state. Delivery and review follow the user's authorized scope and
+[review loop](../../../docs/PR_REVIEW_LOOP.md).
+
+For current command flags use command-specific help/contracts. Optional deeper
+workflow guidance is available after installing guide-shell:
+
+```bash
+pm package install guide-shell --project
+pm guide workflows --depth brief
+```

package/.agents/skills/pm-test-audit/references/AUDIT.md

@@ -0,0 +1,54 @@
+# Evidence Before Removing a Test
+
+Start with read-only discovery. Test count, runtime, coverage percentage, or a
+suspicious name is a lead, not proof that a test is low-value.
+
+## Candidates to Investigate
+
+- Assertion-free probes, self-comparisons, or expected values calculated by the
+  same implementation under test.
+- Copied export/manifest inventories or source-text checks without an independent
+  compatibility, packaging, security, or architecture contract.
+- Private predicate, mock-call-shape, and wiring assertions that repeat stronger
+  observable behavior coverage.
+- Identical scenarios across SDK, CLI, MCP, and packages without distinct
+  boundary failure modes; prefer a named keeper over another copy.
+- Fixtures that pre-seed the receipt, ordering, admission, or callback result the
+  production owner should produce; persistence tests that never write anything.
+- Tests that assert a flag was forwarded but never prove its promised behavior.
+- Test-only production exports, globals, wrappers, dead branches, or injected
+  switches with no supported consumer contract.
+- Negative controls that fail at an unrelated guard, and names claiming behavior
+  that their assertions never observe.
+
+Read the complete test and production owner, trace non-test callers and relevant
+callees, and inspect overlapping tests, CI routing, history, and configuration.
+Do not assume no in-repo caller means a published SDK export is unused.
+
+## Reasons to Retain
+
+Keep independent public SDK, protocol, configuration, migration, storage,
+security, platform, default, package/release, and generated cross-language
+contracts. Observable ordering can be a contract. Static inspection can be the
+cheapest independent architectural guard; ask whether it survives harmless
+identifier refactoring. Slowness and use of mocks are not deletion criteria on
+their own. A previously failing retained test may expose a product defect.
+
+## Candidate Ledger
+
+For each candidate, record:
+
+| Evidence | Required detail |
+| --- | --- |
+| Identity | Exact path and test/table row; production owner and callers |
+| Failure | Credible regression the assertion can detect |
+| Contract | Independent external obligation, or why none exists |
+| Overlap | Named keeper and distinct behavior it still proves |
+| Seam | Production change deletion would permit, or none |
+| Decision | Retain, repair, consolidate, or delete, with rationale |
+| Verification | Exact command, negative control where appropriate, and result |
+
+Establish the keeper before removing duplicates. Remove private obsolete seams
+only after caller and public-contract checks. Prefer simpler production code,
+but do not use net lines deleted as a success quota. Avoid trivial one-use
+wrappers or test helpers that merely mirror the implementation.

package/.agents/skills/pm-test-audit/references/CAMPAIGN.md

@@ -0,0 +1,47 @@
+# Broad Test Audit Campaign
+
+Use only for an authorized broad sweep. Adapted from the upstream
+[campaign procedure](https://github.com/openclaw/openclaw/blob/e0d80000067d224e93af6107ed093a21e046879f/.agents/skills/test-audit/CAMPAIGN.md).
+
+1. **Pin a baseline.** Record the commit, test inventory, full-suite outcomes,
+   coverage, and existing failures in the canonical pm item. Baseline failures
+   are investigations, not permission to discard tests. Check all-status lineage
+   before creating follow-ups.
+2. **Partition by owner.** Include SDK domains, CLI/MCP adapters, packages,
+   release scripts, plugins, and shared harnesses within the requested scope.
+   Assign each test one lane. If delegation is authorized, use read-only
+   discovery lanes first and a single integration owner for shared harnesses.
+3. **Build the ledger.** Apply [audit evidence](AUDIT.md) to every declaration in
+   scope; distinguish table rows with different contracts. Mark retain, repair,
+   consolidate, or delete. Record uncovered/unread inventory explicitly instead
+   of claiming a complete sweep.
+4. **Consolidate with proof.** Name and strengthen the keeper first. Preserve
+   real SDK behavior and distinct CLI/MCP serialization, error, lifecycle,
+   persistence, package, and release guarantees. A fake external service can be
+   useful; a mock implementing the production algorithm proves nothing.
+5. **Integrate coherently.** Serialize shared build/harness edits, remove only
+   obsolete private seams, and update routing/inventory when required. Preserve
+   the canonical coverage denominator and every mandatory gate. Do not weaken
+   caps, thresholds, documentation requirements, or lint rules to pass.
+6. **Check preservation independently.** Revisit each removed contract against
+   the keeper and current production boundary. Use targeted mutations or pre-fix
+   controls in an isolated copy with temporary `PM_PATH` and `PM_GLOBAL_PATH`
+   for every direct stateful CLI command to establish meaningful failure. Record exact
+   changed bytes, failure reason, restoration, and passing rerun. Never mutate
+   the working tree under a running test command.
+7. **Handle product defects explicitly.** Track a real defect separately within
+   the coherent delivery, with failing-before/passing-after proof and the
+   repository's structured defect evidence. Reuse existing lineage; do not hide
+   unrelated repairs inside mass test deletion.
+8. **Reconcile and verify.** Incorporate upstream changes without force-pushing
+   shared history. Reassess newly introduced contracts rather than blindly
+   preserving deletions. Run focused tests, full suite/coverage, static quality,
+   and affected acceptance/package/performance gates on the integrated tree.
+9. **Hand off honestly.** Report baseline and final counts, covered lanes, named
+   keepers, production seams removed, regressions demonstrated, full commands,
+   results, and remaining risks. A review inventory is not a correctness
+   certificate. Follow the authorized PR workflow; unavailable reviewers are
+   unavailable evidence, not approval.
+
+Update pm files/docs/tests/comments and durable learnings as evidence accrues.
+Close only implemented work with structured results and release ownership.

package/.claude-plugin/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.26"
   },
   "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.26",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/AGENTS.md

@@ -58,27 +58,13 @@ On a fresh clone or worktree, also run `pm merge install` once: the committed `.
 For real repository tracking, do not override `PM_PATH`. If a script must target a tracker explicitly, prefer `--pm-path <repo>/.agents/pm`; `--path` is only a backward-compatible tracker-root alias, not a workspace/cwd flag. For tests and dogfood runs, use sandboxed `PM_PATH` and `PM_GLOBAL_PATH`; prefer `node scripts/run-tests.mjs ...` because it sets them automatically.
 
 <!-- pm-cli:agent-guidance:start:v1 -->
+## pm Workflow (Agent Quickstart)
 
-## pm Workflow Quickstart
-
-```bash
-pm context --limit 10 --for orient
-pm search "<request keywords>" --limit 10
-pm list --status open --limit 20
-pm list --status in_progress --limit 20
-pm create --create-mode progressive --title "..." --description "..." --type Task --status open
-pm claim <id>
-pm update <id> --status in_progress --message "Start implementation"
-pm files <id> --add path=<path>,scope=project,note="<why>"
-pm docs <id> --add path=<path>,scope=project,note="<why>"
-pm test <id> --add command="node scripts/run-tests.mjs test -- <target>",scope=project,timeout_seconds=240
-pm comments <id> "Evidence: <what changed and what passed>"
-pm test <id> --run --progress
-pm close <id> "<reason with evidence>" --resolution "<what changed>" --expected "<expected outcome>" --actual "<observed outcome>" --validate-close warn
-pm release <id>
-```
-
-Author identity is automatic; use `--author` only for an explicit override.
+- Cold start with the measured canonical orientation: `pm context --limit 10 --for orient`; before item mutation, also run `pm search "<keywords>" --limit 10`, `pm list --status open --limit 20`, and `pm list --status in_progress --limit 20`.
+- Claim and start atomically: `pm claim <id> --start`.
+- Link evidence while coding: `pm files <id> --add ...`, `pm docs <id> --add ...`, `pm test <id> --add command="node scripts/run-tests.mjs test"`.
+- Verify and close: `pm test <id> --run --progress`, then atomically record closure evidence with `pm close <id> "<reason>" --resolution "<what changed>" --expected "<expected outcome>" --actual "<observed outcome>" --validate-close warn`, then `pm release <id>`.
+- Author identity is automatic for supported agent harnesses; use `--author` only for an explicit override.
 
 <!-- pm-cli:agent-guidance:end -->
 

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 2026.9.26 - 2026-09-26
+
+### Fixed
+
+- Refuse unsupported schema dry-run flags before mutation ([pm-s74dca](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-s74dca.toon))
+- Releases from the default branch are supported with analyzer evidence ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
+
+### Other
+
+- Adapt OpenClaw test-audit skill to pm SDK and repository test governance ([pm-xvibt6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-xvibt6.toon))
+- Bound embedding requests, enforce retrieval floors, and protect schema previews ([pm-g0b88h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/changesets/pm-g0b88h.toon))
+
+## 2026.9.25 - 2026-09-25
+
+### Fixed
+
+- GH-1306: Isolate merge driver installation and health across Git worktrees ([pm-c1dwbt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-c1dwbt.toon))
+- GH-1305: Preserve workflow policy refusal evidence and actionable missing-field recovery ([pm-o5s22y](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-o5s22y.toon))
+- GH-1303: Canonical help and refreshable agent guidance ([pm-80k965](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-80k965.toon))
+- GH-1304: Deterministic release pipeline branch coverage across hosted environments ([pm-m2ai6c](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-m2ai6c.toon))
+- Scheduled auto-release has a chronically high failure rate and no rolling measure, so a degraded pipeline reads as healthy one run at a time ([pm-e70zh5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-e70zh5.toon))
+- Daily auto-release never runs in its declared window: all 84 scheduled runs fired 2.5-4 hours after the cron time, so the release clock is undocumented drift ([pm-44u3wt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-44u3wt.toon))
+- GH-1294: release commit omits synchronized plugin runtime manifests ([pm-t4prek](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-t4prek.toon))
+- The related ceiling is pinned to the live count with block enforcement, so recording one associative sibling relation anywhere in the tracker fails CI while the share floor it duplicates would have allowed it ([pm-r3o7x4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-r3o7x4.toon))
+
+### Security
+
+- Semgrep 874840452: Medium dependabot missing cooldown in .github/dependabot.yml\#L3 ([pm-gkut](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gkut.toon))
+- Semgrep 874840451: Medium dependabot missing cooldown in .github/dependabot.yml\#L23 ([pm-dmo5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dmo5.toon))
+
+## 2026.9.24 - 2026-09-24
+
+### Fixed
+
+- Dogfood test failure must not print inherited environment secrets ([pm-jiv3dw](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-jiv3dw.toon))
+- Claude plugin: marketplace installs fall back to npx @latest, not the advertised native MCP server ([pm-l9wl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-l9wl.toon))
+- Windows copied agent plugins cannot install pinned runtime through npm.cmd ([pm-d6fd85](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-d6fd85.toon))
+- Nightly coverage, quality, and Windows tests exceed serial job budgets ([pm-ul9rye](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ul9rye.toon))
+- GH-1291: Windows nightly release cleanup fixture includes Node compile cache ([pm-puf5rq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-puf5rq.toon))
+
+### Security
+
+- Scorecard Token-Permissions (0→10): declare least-privilege top-level permissions in every GitHub workflow ([pm-003j](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-003j.toon))
+
+### Other
+
+- Support safe Bash completion inside quoted and escaped prefixes ([pm-eswzn9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-eswzn9.toon))
+- Refresh compatible Sentry, jscpd, and TypeScript-ESLint patches for September 22 ([pm-hate9s](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-hate9s.toon))
+
 ## 2026.9.23 - 2026-09-23
 
 ### Other
@@ -313,7 +362,6 @@
 - Metadata index rebuilds and mutations repeatedly scan an unindexed FTS identity column ([pm-gtw5zh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gtw5zh.toon))
 - Read sessions emit invalid continuation identities from workspace activity rows ([pm-s8ybl9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-s8ybl9.toon))
 - Scale fixtures silently omit unregistered Story items from metadata reads ([pm-fx80w2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fx80w2.toon))
-- Releases from the default branch are supported with analyzer evidence ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
 
 ### Other
 

package/dist/cli/error-guidance.d.ts

@@ -6,6 +6,8 @@
 import { type PmCliErrorContext, type PmCliErrorRecoveryPayload } from "../sdk/runtime-primitives.js";
 import { type PmDiagnosticOutputReceipt, type PmProjectedDiagnostic } from "../sdk/cli-contracts/agent-output-contracts.js";
 interface GuidanceMessage {
+    policyViolations?: PmCliErrorContext["policy_violations"];
+    policyViolationCount?: number;
     itemId?: string;
     tombstone?: PmCliErrorContext["tombstone"];
     code: string;
@@ -31,6 +33,12 @@ export interface PmRefusalEnvelope {
     rejected_value?: string;
     /** Complete legal domain advertised by the refusal, when applicable. */
     legal_domain?: string[];
+    /** Required metadata paths from the displayed policy violations. */
+    missing_fields?: string[];
+    /** Policy identity, rule, rationale and missing fields, capped at three policies. */
+    policies?: PmCliErrorContext["policy_violations"];
+    /** Total violated policies, including any omitted from policies. */
+    policy_violation_count?: number;
     /** Process exit code paired with the refusal. */
     exit_code: number;
 }
@@ -166,6 +174,7 @@ declare function guidanceToJsonEnvelope(message: GuidanceMessage, exitCode: numb
 declare function guidanceToClassification(message: GuidanceMessage): ErrorClassification;
 declare function dedupeStrings(values: string[]): string[];
 declare function buildFallbackTitleFromMessage(message: string): string | undefined;
+/** Merge SDK error evidence with CLI fallback guidance without discarding typed recovery or policy diagnostics. */
 declare function applyPmCliErrorContext(guidance: GuidanceMessage, rawMessage: string, context: PmCliErrorContext | undefined): GuidanceMessage;
 declare function commandExampleForRequiredOption(commandName: string | undefined, optionFlag: string, allowedTypes: string): string[];
 declare function buildCommanderRecoveryPayload(context: CommanderGuidanceContext | undefined, overrides?: Partial<PmCliErrorRecoveryPayload>): PmCliErrorRecoveryPayload | undefined;