Docs freshness sweep (28 MCP tools, Node 22.18, package caveats) + CI least-privilege hardening

Merged
UN
4mo ago
+341-53

Applies the fixes queued by the 2026-07-02 full ecosystem audit (umbrella [pm-fpod], lanes pm-kes3/pm-6vy7/pm-hfli/pm-3l76/pm-p99b/pm-mo2v): documentation freshness + progressive disclosure, and CI/CD least-privilege hardening.

Docs freshness (Lane E, pm-p99b)

  • 26 → 28 MCP tools everywhere the stale count survived: README.md, plugins/pm-claude/README.md (×3 sites), plugins/pm-claude/.claude-plugin/plugin.json, plugins/pm-claude/commands/pm-init.md; the plugin narrow-tool table gains the missing pm_next, pm_focus, pm_profile rows (27 narrow + pm_run), and the pm-init tool list now names all 28. Plugin version bumped 1.4.0 → 1.4.1.
  • Node 20 → 22.18 (matches engines >=22.18.0): CONTRIBUTING.md, docs/ARCHITECTURE.md, docs/ONBOARDING.md.
  • Stale CI matrix in CONTRIBUTING.md: now ubuntu-latest (Node 22, 24) + macos-latest (Node 24), nightly for Windows/Node 25 — matching ci.yml.
  • Package-only commands no longer read as core: comments-audit/normalize (governance-audit) and test-runs† (linked-test-adapters) footnoted in docs/COMMANDS.md; caveats added at first mention for reindex/normalize (AGENT_GUIDE), normalize (ONBOARDING), calendar (CONFIGURATION), reindex (ARCHITECTURE); pm completion section notes it comes from guide-shell.
  • Deduplicated the 10-capability scaffold matrix: docs/EXTENSIONS.md now summarizes and links to the canonical matrix in docs/SDK.md instead of restating it (also keeps EXTENSIONS.md under its 450-line gate).
  • Canonical-loop duplication: docs/ONBOARDING.md now declares AGENT_GUIDE.md as the canonical loop source.
  • starter-extension example switched to package-first vocabulary (pm install <path> --project, pm package --reload, pm package doctor), noting pm extension --install remains a compatibility form.
  • Orphan links fixed: docs/README.md links AGENTS.md + PRD.md; docs/EXTENSIONS.md first-party package list now links all 11 package READMEs.
  • Six built-in statuses wording fix (was "five ... plus draft").

CI/CD hardening (Lane F, pm-mo2v)

  • auto-release.yml: actions: write → actions: read (gh run list/watch only read run state).
  • scripts/check-secrets-lib.mjs: new anthropic-api-key (sk-ant-…), openai-api-key (sk-…/sk-proj-…/sk-svcacct-…), and gitlab-token (glpat-…) rules + spec coverage; repo-wide scan stays clean.
  • Live repo settings (gh api, no code): release environment now restricted by deployment branch policy to main + v*.*.* tags (covers both auto-release.yml on main and tag-triggered release.yml).
  • Declined: secret_scanning_non_provider_patterns / secret_scanning_validity_checks require paid GitHub Secret Protection (PATCH is silently ignored on the free plan) — documented on pm-mo2v.

Audit follow-ups filed (not in this PR)

  • [pm-3wsi] P1: declarative extension install misreports activation failure when @unbrained/pm-cli is unresolvable
  • [pm-ghf1] P2: reserved item-field collisions invisible to SDK lint/preflight/harness
  • [pm-llrp] P3: SDK authoring DX polish bundle
  • [pm-gdi7] P2: agent-UX output polish (unknown-option suggestions, list-closed projection, schema add-field help)
  • [pm-z1pv] P2: pm context/pm next hot path ~700ms on an 857-item tracker

Verification

  • pnpm build, pnpm typecheck, npx eslint . (zero output), docs-skills gate, node scripts/check-secrets.mjs clean, Claude-plugin smoke, full coverage suite green (see checks).
  • pnpm changelog:pm:check green after regeneration (audit-lane closes recorded under Unreleased).

🤖 Generated with Claude Code

https://claude.ai/code/session_01FM3GimxcR6DpRdMiBX3RLs

Summary by cubic

Refreshes docs to match the current ecosystem (28 MCP tools, Node 22.18, package-provided commands) and hardens CI with least-privilege permissions and stronger secret scanning, including GitLab routable PATs. Keeps plugin/marketplace metadata in sync and trims duplicated docs.

  • Docs Freshness

    • Updated 26 → 28 MCP tools across README.md, plugin docs, and manifests; added pm_next, pm_focus, pm_profile; bumped pm-claude to 1.4.1 in plugin and both marketplace manifests.
    • Set Node requirement to 22.18 in CONTRIBUTING.md, docs/ARCHITECTURE.md, and docs/ONBOARDING.md; aligned CI matrix docs to ubuntu-latest (Node 22, 24) and macos-latest (Node 24), with nightly Windows/Node 25.
    • Clarified package-provided commands and caveats: comments-audit/normalize from governance-audit, test-runs from linked-test-adapters, pm completion from guide-shell; noted reindex/normalize/calendar require packages (e.g., search-advanced, governance-audit, calendar).
    • Reduced duplication and fixed links: EXTENSIONS.md links to the canonical SDK matrix; ONBOARDING.md points to AGENT_GUIDE.md; starter example uses package-first (pm install, pm package --reload, pm package doctor).

  • CI/CD Hardening

    • Dropped auto-release.yml permissions to actions: read; updated the workflow contract test.
    • Expanded and refined secret scanning with tests: Anthropic (sk-ant-), OpenAI (sk- incl. sk-proj-/sk-svcacct- with a negative lookahead to avoid sk-ant-), and GitLab (glpat-), now including routable PATs with dots.
    • Restricted the release environment to main and v*.*.* tags via deployment branch policy.