Adopt the canonical pm-ops docstring gate

.agents/pm/history/pm-github-pbxd.jsonl

@@ -0,0 +1,4 @@
+{"ts":"2026-08-09T06:24:47.743Z","author":"pi-agent","author_source":"asserted","agent_harness":"pi","agent_model":"glm-5.2","agent_model_source":"environment","agent_instance":"ca9cfbda1fa8ac386a999484","agent_provenance":{"model":{"value":"glm-5.2","source":"environment"},"effort":null,"role":null,"topic":null},"op":"create","patch":[{"op":"add","path":"/metadata/id","value":"pm-github-pbxd"},{"op":"add","path":"/metadata/title","value":"Adopt the canonical pm-ops docstring gate"},{"op":"add","path":"/metadata/description","value":"Adopt the canonical pm-ops docstring coverage analyzer as the single fleet-wide docstring gate: add pm-ops as a devDependency, a thin scripts/docstring-gate.ts launcher that calls analyzeDocstringCoverage (no vendored analyzer), wire it into release:check and CI, and write real JSDoc for every flagged declaration until the gate reports zero violations."},{"op":"add","path":"/metadata/type","value":"Task"},{"op":"add","path":"/metadata/status","value":"open"},{"op":"add","path":"/metadata/priority","value":2},{"op":"add","path":"/metadata/tags","value":[]},{"op":"add","path":"/metadata/created_at","value":"2026-08-09T06:24:47.743Z"},{"op":"add","path":"/metadata/updated_at","value":"2026-08-09T06:24:47.743Z"},{"op":"add","path":"/metadata/author","value":"pi-agent"},{"op":"add","path":"/metadata/acceptance_criteria","value":"scripts/docstring-gate.ts is a thin launcher over pm-ops/docstrings analyzeDocstringCoverage (no vendored/forked analyzer); npm run docstring reports zero violations (72 violations fixed across index.ts and projects.ts); release:check is fully green: typecheck, build, docstring, coverage, audit, pack dry-run, changelog check; CI runs a 'Verify complete docstring coverage' step immediately after build, before the coverage step (no existing step renamed); a behavioral test covers the gate runGate/main/isMainInvocation wiring"}],"before_hash":"3cc22dff72be7b14824654a7a64ea62b04799939b2fee54c1b5f52ca60bf6df0","after_hash":"4ffa68dc1e5f8188ef7388416c46e09cfec0020a5a12aa73b3555dbecb5628c3","message":""}
+{"ts":"2026-08-09T06:24:57.606Z","author":"pi-agent","author_source":"asserted","agent_harness":"pi","agent_model":"glm-5.2","agent_model_source":"environment","agent_instance":"ca9cfbda1fa8ac386a999484","agent_provenance":{"model":{"value":"glm-5.2","source":"environment"},"effort":null,"role":null,"topic":null},"op":"update","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-08-09T06:24:57.606Z"},{"op":"replace","path":"/metadata/status","value":"in_progress"}],"before_hash":"4ffa68dc1e5f8188ef7388416c46e09cfec0020a5a12aa73b3555dbecb5628c3","after_hash":"9d0f574d0131be886d232565ee8879bf3f095696f0f037f5b690789cf5d399d0"}
+{"ts":"2026-08-09T06:24:58.021Z","author":"pi-agent","author_source":"asserted","agent_harness":"pi","agent_model":"glm-5.2","agent_model_source":"environment","agent_instance":"ca9cfbda1fa8ac386a999484","agent_provenance":{"model":{"value":"glm-5.2","source":"environment"},"effort":null,"role":null,"topic":null},"op":"note_add","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-08-09T06:24:58.021Z"},{"op":"add","path":"/metadata/notes","value":[{"created_at":"2026-08-09T06:24:58.021Z","author":"pi-agent","text":"Docstring gate initially reported 72 violations across index.ts (62) and projects.ts (10); added a self-contained scripts/docstring-gate.ts launcher over pm-ops/docstrings analyzeDocstringCoverage (no shared launcher module, matching this repo's coverage-gate.ts style), a behavioral test, and real JSDoc for every flagged declaration. Gate now reports 0 violations (4 files, 85 declarations documented)."}]}],"before_hash":"9d0f574d0131be886d232565ee8879bf3f095696f0f037f5b690789cf5d399d0","after_hash":"fad0e7556d6d0f8e470877ced7ac95d38fb3b1e790f7eb06eb1354a5e4508be4"}
+{"ts":"2026-08-09T06:25:06.660Z","author":"pi-agent","author_source":"asserted","agent_harness":"pi","agent_model":"glm-5.2","agent_model_source":"environment","agent_instance":"ca9cfbda1fa8ac386a999484","agent_provenance":{"model":{"value":"glm-5.2","source":"environment"},"effort":null,"role":null,"topic":null},"op":"close","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-08-09T06:25:06.660Z"},{"op":"replace","path":"/metadata/status","value":"closed"},{"op":"add","path":"/metadata/closed_at","value":"2026-08-09T06:25:06.644Z"},{"op":"add","path":"/metadata/completed_at","value":"2026-08-09T06:25:06.644Z"},{"op":"add","path":"/metadata/close_reason","value":"Docstring gate adopted: pm-ops 2026.8.8 devDependency, self-contained scripts/docstring-gate.ts launcher + test, release:check and CI wired, 72 violations fixed to 0. Full release:check green."}],"before_hash":"fad0e7556d6d0f8e470877ced7ac95d38fb3b1e790f7eb06eb1354a5e4508be4","after_hash":"6610d9fb203e77c9834e371a6000d8b8842d49fabde2e5bf2f404ad7bc1de9b8"}

.agents/pm/history/pm-github-wxob.jsonl

@@ -0,0 +1,3 @@
+{"ts":"2026-08-09T12:55:45.761Z","author":"claude","author_source":"asserted","agent_harness":"claude-code","agent_instance":"6c62aab177c939482aa0465b","agent_provenance":{"model":null,"effort":{"value":"xhigh","source":"environment"},"role":{"value":"1","source":"environment"},"topic":null},"op":"create","patch":[{"op":"add","path":"/metadata/id","value":"pm-github-wxob"},{"op":"add","path":"/metadata/title","value":"The mandatory docstring gate could skip its own scan and still exit zero"},{"op":"add","path":"/metadata/description","value":"isMainInvocation resolved this module's own path inside a try block that swallowed every failure and returned false. Returning false leaves main() unreached and process.exitCode at zero, so a release could pass the mandatory docstring gate having scanned nothing. The two resolutions now differ: an unresolvable argv[1] still answers false because that is the ordinary imported-by-a-test case, while an unresolvable own module path throws. A regression test asserts the throw and was mutation-checked by reverting the fix, which makes it fail."},{"op":"add","path":"/metadata/type","value":"Issue"},{"op":"add","path":"/metadata/status","value":"open"},{"op":"add","path":"/metadata/priority","value":2},{"op":"add","path":"/metadata/tags","value":[]},{"op":"add","path":"/metadata/created_at","value":"2026-08-09T12:55:45.761Z"},{"op":"add","path":"/metadata/updated_at","value":"2026-08-09T12:55:45.761Z"},{"op":"add","path":"/metadata/author","value":"claude"}],"before_hash":"3cc22dff72be7b14824654a7a64ea62b04799939b2fee54c1b5f52ca60bf6df0","after_hash":"cbba035fac2e8093d751f8801353f61d1cba0e640b5700fc2bd82f4453bb5dc2","message":""}
+{"ts":"2026-08-09T12:57:17.194Z","author":"claude","author_source":"asserted","agent_harness":"claude-code","agent_instance":"6c62aab177c939482aa0465b","agent_provenance":{"model":null,"effort":{"value":"xhigh","source":"environment"},"role":{"value":"1","source":"environment"},"topic":null},"op":"note_add","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-08-09T12:57:17.194Z"},{"op":"add","path":"/metadata/notes","value":[{"created_at":"2026-08-09T12:57:17.194Z","author":"claude","text":"Mutation-checked in pm-slack by reverting the split resolution back to the single try block, which makes the new test fail; the identical fix and test ship here."}]}],"before_hash":"cbba035fac2e8093d751f8801353f61d1cba0e640b5700fc2bd82f4453bb5dc2","after_hash":"0dbf2be861ce10ec753092478c12e94273c68439e6445cf4aecb4fc3c5fcb56f"}
+{"ts":"2026-08-09T12:57:17.626Z","author":"claude","author_source":"asserted","agent_harness":"claude-code","agent_instance":"6c62aab177c939482aa0465b","agent_provenance":{"model":null,"effort":{"value":"xhigh","source":"environment"},"role":{"value":"1","source":"environment"},"topic":null},"op":"close","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-08-09T12:57:17.626Z"},{"op":"replace","path":"/metadata/status","value":"closed"},{"op":"add","path":"/metadata/closed_at","value":"2026-08-09T12:57:17.611Z"},{"op":"add","path":"/metadata/completed_at","value":"2026-08-09T12:57:17.611Z"},{"op":"add","path":"/metadata/resolution","value":"fixed"},{"op":"add","path":"/metadata/expected_result","value":"A docstring gate whose own path cannot be resolved must fail the release rather than exit zero having scanned nothing."},{"op":"add","path":"/metadata/actual_result","value":"isMainInvocation throws on self-resolution failure; a regression test asserts the throw and the suite passes."},{"op":"add","path":"/metadata/close_reason","value":"Split the two path resolutions so only an unresolvable argv[1] answers false; an unresolvable own module path now throws."}],"before_hash":"0dbf2be861ce10ec753092478c12e94273c68439e6445cf4aecb4fc3c5fcb56f","after_hash":"9af057081e9104f8a71e86fdef654556b14764f50ab40d824bbf5c02af306522"}

.agents/pm/issues/pm-github-wxob.toon

@@ -0,0 +1,19 @@
+id: pm-github-wxob
+title: The mandatory docstring gate could skip its own scan and still exit zero
+description: "isMainInvocation resolved this module's own path inside a try block that swallowed every failure and returned false. Returning false leaves main() unreached and process.exitCode at zero, so a release could pass the mandatory docstring gate having scanned nothing. The two resolutions now differ: an unresolvable argv[1] still answers false because that is the ordinary imported-by-a-test case, while an unresolvable own module path throws. A regression test asserts the throw and was mutation-checked by reverting the fix, which makes it fail."
+type: Issue
+status: closed
+priority: 2
+tags: []
+created_at: "2026-08-09T12:55:45.761Z"
+updated_at: "2026-08-09T12:57:17.626Z"
+closed_at: "2026-08-09T12:57:17.611Z"
+completed_at: "2026-08-09T12:57:17.611Z"
+author: claude
+resolution: fixed
+expected_result: A docstring gate whose own path cannot be resolved must fail the release rather than exit zero having scanned nothing.
+actual_result: isMainInvocation throws on self-resolution failure; a regression test asserts the throw and the suite passes.
+notes[1]{created_at,author,text}:
+  "2026-08-09T12:57:17.194Z",claude,"Mutation-checked in pm-slack by reverting the split resolution back to the single try block, which makes the new test fail; the identical fix and test ship here."
+close_reason: "Split the two path resolutions so only an unresolvable argv[1] answers false; an unresolvable own module path now throws."
+body: ""

.agents/pm/tasks/pm-github-pbxd.toon

@@ -0,0 +1,17 @@
+id: pm-github-pbxd
+title: Adopt the canonical pm-ops docstring gate
+description: "Adopt the canonical pm-ops docstring coverage analyzer as the single fleet-wide docstring gate: add pm-ops as a devDependency, a thin scripts/docstring-gate.ts launcher that calls analyzeDocstringCoverage (no vendored analyzer), wire it into release:check and CI, and write real JSDoc for every flagged declaration until the gate reports zero violations."
+type: Task
+status: closed
+priority: 2
+tags: []
+created_at: "2026-08-09T06:24:47.743Z"
+updated_at: "2026-08-09T06:25:06.660Z"
+closed_at: "2026-08-09T06:25:06.644Z"
+completed_at: "2026-08-09T06:25:06.644Z"
+author: pi-agent
+acceptance_criteria: "scripts/docstring-gate.ts is a thin launcher over pm-ops/docstrings analyzeDocstringCoverage (no vendored/forked analyzer); npm run docstring reports zero violations (72 violations fixed across index.ts and projects.ts); release:check is fully green: typecheck, build, docstring, coverage, audit, pack dry-run, changelog check; CI runs a 'Verify complete docstring coverage' step immediately after build, before the coverage step (no existing step renamed); a behavioral test covers the gate runGate/main/isMainInvocation wiring"
+notes[1]{created_at,author,text}:
+  "2026-08-09T06:24:58.021Z",pi-agent,"Docstring gate initially reported 72 violations across index.ts (62) and projects.ts (10); added a self-contained scripts/docstring-gate.ts launcher over pm-ops/docstrings analyzeDocstringCoverage (no shared launcher module, matching this repo's coverage-gate.ts style), a behavioral test, and real JSDoc for every flagged declaration. Gate now reports 0 violations (4 files, 85 declarations documented)."
+close_reason: "Docstring gate adopted: pm-ops 2026.8.8 devDependency, self-contained scripts/docstring-gate.ts launcher + test, release:check and CI wired, 72 violations fixed to 0. Full release:check green."
+body: ""

.github/workflows/ci.yml

@@ -67,6 +67,9 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Verify complete docstring coverage
+        run: npm run docstring
+
       - name: Test with coverage gate
         run: npm run coverage
 

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+
+- The mandatory docstring gate could skip its own scan and still exit zero ([pm-github-wxob](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-wxob.toon))
+
+### Other
+
+- Adopt the canonical pm-ops docstring gate ([pm-github-pbxd](https://github.com/unbraind/pm-github/blob/main/.agents/pm/tasks/pm-github-pbxd.toon))
+
 ## 2026.8.7 - 2026-08-07
 
 ### Other