PR #58 - unbraind/pm-linear

Summary

Adopts the fleet's canonical pm-ops/docstrings analyzer (pm-ops@^2026.8.8) as a mandatory release gate, and documents every source declaration it requires. No docstring-gate fork is copied — the thin launcher imports analyzeDocstringCoverage from pm-ops/docstrings, so this repo shares the one lexer-backed policy instead of drifting another copy.

Before / after (canonical analyzer)

	files	declarations	violations	documented
before	2	37	34	8%
after	4	42	0	100%

npm run docstring → docstring-gate: 4 file(s), 42 declaration(s) documented.

Changes

scripts/docstring-gate.ts + scripts/script-launcher.ts: copied from pm-rl's reference adoption — a pure runGate(root) returning {exitCode, stdout, stderr} (assertable from a test) and a main(root) that writes the streams and sets process.exitCode (never process.exit).
package.json: pm-ops@^2026.8.8 added to devDependencies (build-time gate, not a runtime dependency); new docstring script inserted into release:check.
.github/workflows/ci.yml: a Verify complete docstring coverage step (plus a standalone Build step), placed before the coverage gate.
test/docstring-gate.test.ts: covers the clean path (real repo), the violation path (undocumented source), and the main/isMainInvocation/runIfMain entry points.
index.ts: meaningful JSDoc on all 34 previously-undocumented declarations (no identifier-restating filler).

Why not a fork

pm-changelog and pm-vcs each ship a 500-line docstring-gate.ts fork that pins typescript5 to dodge the TS7 scanner. pm-ops already solved that (it rescans template-substitution } and only treats / as regex in regex context), so copying a fork into more repos just creates more drift. pm-changelog passes its own fork inside release:check while the canonical analyzer finds 5 violations in it — a gate that passes while the stricter policy finds violations is not enforcing the policy it claims to.

Gates

npm run release:check is green end to end: typecheck → build → docstring → coverage (70/80/80 thresholds met) → audit:prod (0 vulns) → pack:dry-run → changelog:check.

pm item

pm-linear-085x

Summary by Sourcery

Adopt the shared pm-ops docstring coverage analyzer as a mandatory release gate and document all relevant source declarations to satisfy it.

New Features:

Add a docstring gate script that launches the canonical pm-ops docstring analyzer against the repository.
Introduce a shared script launcher utility that standardizes main-module detection and gate result contracts across operational scripts.

Enhancements:

Add comprehensive JSDoc documentation to previously undocumented types, helpers, and operational logic in the main extension module.
Refine operational helpers around Linear integration with clearer contracts and behavior descriptions (errors, retries, provenance, mapping utilities).

Build:

Wire the docstring gate into npm scripts and the release:check pipeline, and add pm-ops as a dev dependency to supply the canonical analyzer.

CI:

Extend the CI workflow with explicit build and docstring coverage verification steps before the coverage gate.

Chores:

Record the associated pm work item in the agents history and issues tracking files.

Summary by cubic

Adopted the canonical pm-ops/docstrings analyzer as a required release/CI gate and documented all source declarations, reducing violations from 34 to 0. This standardizes docstring policy across repos and blocks releases with missing docs.

New Features
- Thin launcher (scripts/docstring-gate.ts + scripts/script-launcher.ts) that imports analyzeDocstringCoverage from pm-ops/docstrings.
- Added npm run docstring; wired into release:check and CI (after Build, before coverage); added pm-ops@^2026.8.8 as a dev dependency.
- Tests for clean/violation paths and the main/isMainInvocation entry points.
- Added meaningful JSDoc in index.ts; repo now reports full coverage.
- Satisfies Linear issue pm-linear-085x.
Bug Fixes
- Removed an unused isMainInvocation import in the gate script to clear a static analysis warning.