docguard-cli 0.34.2__tar.gz → 0.34.4__tar.gz

{docguard_cli-0.34.2/extensions/spec-kit-docguard → docguard_cli-0.34.4/.agent}/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.34.2
+  version: 0.34.4
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.34.2 -->
+<!-- docguard:version: 0.34.4 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.34.2 → docguard_cli-0.34.4}/.agent/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.34.2
+  version: 0.34.4
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.34.2 -->
+<!-- docguard:version: 0.34.4 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.34.2/extensions/spec-kit-docguard → docguard_cli-0.34.4/.agent}/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.34.2
+  version: 0.34.4
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.34.2 -->
+<!-- docguard:version: 0.34.4 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.34.2/extensions/spec-kit-docguard → docguard_cli-0.34.4/.agent}/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.34.2
+  version: 0.34.4
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.34.2 -->
+<!-- docguard:version: 0.34.4 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.34.2 → docguard_cli-0.34.4}/.agent/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.34.2
+  version: 0.34.4
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.34.2 -->
+<!-- docguard:version: 0.34.4 -->
 
 # DocGuard Sync Skill
 

docguard_cli-0.34.4/.github/workflows/auto-merge.yml

@@ -0,0 +1,135 @@
+name: Auto-merge (green bot PRs)
+
+# Hands-off merging for bot PRs that have ALREADY passed the full CI matrix.
+#
+# WHY workflow_run AND NOT `gh pr merge --auto`: GitHub's native auto-merge
+# requires the repo-level `allow_auto_merge` setting plus REQUIRED status
+# checks in branch protection. Without required checks configured, `--auto`
+# merges IMMEDIATELY without waiting for CI — worse than merging by hand.
+# This workflow instead fires only after "DocGuard CI" reports success for
+# the head SHA, re-verifies every matrix leg via the API, and merges itself.
+# No repo settings required, and it is fail-closed: anything unexpected → skip.
+#
+# SECURITY: workflow_run runs in the BASE repo context with write scope, so it
+# NEVER checks out or executes PR code. It reads PR metadata + check results
+# via the API only. (Same rule as jules-triage.yml / AGENTS.md CI rule.)
+#
+# WHAT AUTO-MERGES:
+#   - dependabot: patch + minor only. Majors NEVER (v0.34.1 shipped a Node-18
+#     break from an auto-accepted @babel/parser major; bug-255).
+#   - jules: test-only and docs-only changes. Anything touching cli/ logic,
+#     .github/, or package.json is labeled and left for a human.
+
+on:
+  workflow_run:
+    workflows: ["DocGuard CI"]
+    types: [completed]
+
+permissions:
+  contents: write
+  pull-requests: write
+  checks: read
+  actions: read
+
+jobs:
+  auto-merge:
+    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate and merge if safe
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const run = context.payload.workflow_run;
+            const headSha = run.head_sha;
+
+            // ── Locate the PR for this CI run ────────────────────────────
+            const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+              owner, repo, commit_sha: headSha,
+            });
+            const pr = prs.find((p) => p.state === 'open');
+            if (!pr) { core.info('No open PR for this SHA — nothing to do.'); return; }
+            const num = pr.number;
+            const author = pr.user.login;
+
+            const BOT_DEPENDABOT = 'dependabot[bot]';
+            const BOT_JULES = 'google-labs-jules[bot]';
+            if (![BOT_DEPENDABOT, BOT_JULES].includes(author)) {
+              core.info(`#${num} authored by ${author} (not a handled bot) — leaving alone.`);
+              return;
+            }
+
+            const hold = async (label, why) => {
+              try {
+                await github.rest.issues.addLabels({ owner, repo, issue_number: num, labels: [label] });
+              } catch (e) { core.info(`label skipped: ${e.message}`); }
+              await github.rest.issues.createComment({
+                owner, repo, issue_number: num,
+                body: `⏸️ **Held for human review** — ${why}\n\nCI is green, but this falls outside the auto-merge policy in \`.github/workflows/auto-merge.yml\`.`,
+              });
+              core.notice(`#${num} held: ${why}`);
+            };
+
+            // ── Re-verify EVERY matrix leg independently ─────────────────
+            // workflow_run.conclusion=success covers this run, but be explicit:
+            // all four Node legs must be present AND successful. Fail closed.
+            const { data: checks } = await github.rest.checks.listForRef({
+              owner, repo, ref: headSha, per_page: 100,
+            });
+            const REQUIRED = ['test (18)', 'test (20)', 'test (22)', 'test (24)'];
+            const bad = [];
+            for (const name of REQUIRED) {
+              const c = checks.check_runs.find((r) => r.name === name);
+              if (!c) bad.push(`${name}: missing`);
+              else if (c.conclusion !== 'success') bad.push(`${name}: ${c.conclusion}`);
+            }
+            if (bad.length) {
+              core.info(`#${num} not merging — checks not all green: ${bad.join(', ')}`);
+              return;
+            }
+
+            // ── Scope gate: what files does this PR touch? ───────────────
+            const { data: files } = await github.rest.pulls.listFiles({
+              owner, repo, pull_number: num, per_page: 300,
+            });
+            const paths = files.map((f) => f.filename);
+
+            if (author === BOT_DEPENDABOT) {
+              // Version delta from the title: "bump X from 1.2.3 to 1.2.4"
+              const m = /from (\d+)\.(\d+)\.(\d+)\S* to (\d+)\.(\d+)\.(\d+)/.exec(pr.title || '');
+              if (!m) { await hold('needs-review', 'could not parse the version delta from the PR title.'); return; }
+              const [fromMaj, fromMin] = [Number(m[1]), Number(m[2])];
+              const [toMaj, toMin] = [Number(m[4]), Number(m[5])];
+              if (toMaj !== fromMaj) {
+                await hold('needs-review', `this is a **major** bump (${m[1]}.${m[2]}.${m[3]} → ${m[4]}.${m[5]}.${m[6]}). Majors are never auto-merged — a @babel/parser major silently dropped Node 18 support and broke a release (bug-255).`);
+                return;
+              }
+              core.info(`#${num} dependabot ${toMin !== fromMin ? 'minor' : 'patch'} bump — eligible.`);
+            } else {
+              // Jules: only test-only / docs-only changes auto-merge.
+              const risky = paths.filter((p) =>
+                !(p.startsWith('tests/') || p.startsWith('docs/') || p.endsWith('.md'))
+              );
+              if (risky.length) {
+                await hold('jules-review', `it changes non-test/non-doc files:\n${risky.map((p) => `- \`${p}\``).join('\n')}\n\nProduction-logic changes from an agent get a human read before they ship to npm.`);
+                return;
+              }
+              core.info(`#${num} jules test/docs-only (${paths.length} files) — eligible.`);
+            }
+
+            // ── Merge ────────────────────────────────────────────────────
+            try {
+              await github.rest.pulls.merge({
+                owner, repo, pull_number: num, merge_method: 'squash',
+              });
+              await github.rest.issues.createComment({
+                owner, repo, issue_number: num,
+                body: `🤖 **Auto-merged** — all four Node legs (18/20/22/24) green, within the test-runtime budget, and inside the auto-merge policy in \`.github/workflows/auto-merge.yml\`.`,
+              });
+              core.notice(`Merged #${num}.`);
+            } catch (e) {
+              core.warning(`Merge of #${num} failed: ${e.message}`);
+              await hold('needs-review', `auto-merge failed: \`${e.message}\``);
+            }

{docguard_cli-0.34.2 → docguard_cli-0.34.4}/.github/workflows/ci.yml

@@ -45,8 +45,30 @@ jobs:
         run: python3 -c "import docguard_cli.wrapper; print('docguard_cli.wrapper OK')"
 
       # ── Automated Test Suite ──
-      - name: Run Tests
-        run: npm test
+      # Also enforces a RUNTIME BUDGET. A test that walks an unintended tree
+      # (e.g. passing '/' as a project dir) still PASSES — it just takes
+      # forever. PR #328 did exactly that: tests/schemas.test.mjs went from
+      # 118ms to >10s and the whole suite from ~25s to 190s, green the entire
+      # time. Only a duration check catches that class, so auto-merge depends
+      # on this gate existing. Normal: ~33s (node 24) to ~51s (node 18) on CI.
+      # Budget is deliberately loose — it catches catastrophes, not jitter.
+      - name: Run Tests (with runtime budget)
+        env:
+          TEST_BUDGET_MS: 120000
+        run: |
+          set -o pipefail
+          npm test 2>&1 | tee /tmp/test-output.txt
+          DURATION=$(grep -oE 'duration_ms [0-9]+' /tmp/test-output.txt | tail -1 | grep -oE '[0-9]+' | cut -d. -f1)
+          if [ -z "$DURATION" ]; then
+            echo "::warning::Could not parse test duration — skipping budget check"
+            exit 0
+          fi
+          echo "Test suite duration: ${DURATION}ms (budget: ${TEST_BUDGET_MS}ms)"
+          if [ "$DURATION" -gt "$TEST_BUDGET_MS" ]; then
+            echo "::error::Test suite took ${DURATION}ms, over the ${TEST_BUDGET_MS}ms budget."
+            echo "::error::Something is scanning far more than it should (see PR #328 / bug-254)."
+            exit 1
+          fi
 
       # ── Self-validation (dogfooding) ──
       - name: CLI Version

{docguard_cli-0.34.2 → docguard_cli-0.34.4}/.github/workflows/jules-triage.yml

@@ -52,7 +52,32 @@ jobs:
               .trim();
             const mine = norm(title);
             const { data: open } = await github.rest.pulls.list({ owner, repo, state: 'open', per_page: 100 });
-            const dup = mine && open.find((p) => p.number !== num && norm(p.title) === mine);
+            let dup = mine && open.find((p) => p.number !== num && norm(p.title) === mine);
+
+            // Title-equality alone is too strict: #324 "add tests for untested
+            // shared-ignore utilities", #325 "add missing tests for
+            // shared-ignore functions" and #329 "Add unit tests for
+            // shared-ignore detection utilities" were the SAME work, all three
+            // sat open, and two of them would have collided on the same import
+            // block if merged together. So also treat a PR as a duplicate when
+            // it touches an identical file set to another open Jules PR.
+            // Still metadata-only (listFiles) — never checks out PR code.
+            if (!dup) {
+              const fileSet = async (n) => {
+                const { data } = await github.rest.pulls.listFiles({ owner, repo, pull_number: n, per_page: 300 });
+                return data.map((f) => f.filename).sort().join('|');
+              };
+              try {
+                const mineFiles = await fileSet(num);
+                if (mineFiles) {
+                  for (const p of open) {
+                    if (p.number === num) continue;
+                    if (p.user.login !== 'google-labs-jules[bot]') continue;
+                    if (await fileSet(p.number) === mineFiles) { dup = p; break; }
+                  }
+                }
+              } catch (e) { core.info(`file-overlap dup check skipped: ${e.message}`); }
+            }
 
             const addLabel = async (name) => {
               try {

{docguard_cli-0.34.2 → docguard_cli-0.34.4}/.github/workflows/release.yml

@@ -206,10 +206,25 @@ jobs:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'
 
+      # Trusted Publishing (OIDC) needs npm CLI >= 11.5.0; Node 20's bundled
+      # npm predates that, so self-update first. Pinned to the 11.x line
+      # (NOT `npm@latest`) because npm 12 requires Node ^22.22.2 || ^24.15.0
+      # || >=26.0.0 -- newer than the Node 20 this job runs on. Learned this
+      # the hard way: the first cut of this fix used `npm@latest` and broke
+      # the same way the @babel/parser major bump did earlier (bug-255) --
+      # an unpinned "latest" floated past what this job's Node version
+      # supports. npm 11.x itself supports Node ^20.17.0 || >=22.9.0, so it
+      # installs cleanly here. No NODE_AUTH_TOKEN needed — npm exchanges the
+      # id-token (permissions, above) directly with the registry via the
+      # trusted-publisher connection configured on npmjs.com
+      # (raccioly/docguard, release.yml). This replaces the NPM_TOKEN-based
+      # auth that silently broke for 2 releases (v0.34.1, v0.34.2 never
+      # reached npm) when the token expired — nothing here can expire the
+      # same way; a short-lived token is minted per run.
+      - run: npm install -g npm@11
+
       - name: Publish (with provenance)
         run: npm publish --provenance
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   # ── Step 6: Publish to PyPI ────────────────────────────────────────────
   publish-pypi:

docguard_cli-0.34.4/.github/workflows/scheduled-release.yml

@@ -0,0 +1,137 @@
+name: Scheduled Release
+
+# Self-sustaining releases: batches whatever has landed on main since the last
+# tag into a weekly patch release, instead of cutting a version per merge.
+#
+# WHY BATCHED AND NOT PER-MERGE: every release publishes to npm AND PyPI
+# publicly. Per-merge releases would burn a version number per dependabot
+# patch and publish constantly. Weekly batching keeps releases hands-off
+# without turning the registry into a changelog.
+#
+# HOW IT TRIGGERS THE ACTUAL RELEASE: this workflow only bumps package.json
+# and pushes. release.yml is triggered by pushes that touch package.json, so
+# it picks up from there and does tag → GitHub Release → npm → PyPI → catalog
+# reminder. Keeping the publish logic in one place (release.yml) on purpose.
+#
+# NO-OP WHEN NOTHING CHANGED: if there are no commits since the last release
+# tag, this exits without bumping — no empty releases.
+
+on:
+  schedule:
+    - cron: '0 9 * * 1' # Mondays 09:00 UTC
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: 'Version bump type'
+        required: false
+        default: 'patch'
+        type: choice
+        options: [patch, minor]
+
+permissions:
+  contents: write
+
+jobs:
+  cut-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+
+      - name: Check for unreleased changes
+        id: check
+        run: |
+          CURRENT=$(node -p "require('./package.json').version")
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          echo "current=$CURRENT" >> "$GITHUB_OUTPUT"
+
+          if [ -z "$LAST_TAG" ]; then
+            echo "No tags yet — nothing to compare against, skipping."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Commits since the last tag, excluding the release commits themselves
+          # and the OpenWolf bookkeeping noise (.wolf/ is auto-written by hooks
+          # every session and must never on its own justify a release).
+          COMMITS=$(git log "${LAST_TAG}..HEAD" --oneline -- . ':!.wolf' | grep -viE '^[0-9a-f]+ (release|chore\(release\)):' || true)
+          COUNT=$(echo "$COMMITS" | grep -c . || true)
+
+          echo "Last tag: $LAST_TAG"
+          echo "Releasable commits since: $COUNT"
+          echo "$COMMITS"
+
+          if [ "$COUNT" -eq 0 ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "last_tag=$LAST_TAG" >> "$GITHUB_OUTPUT"
+            # Stash the log for the changelog entry
+            echo "$COMMITS" > /tmp/commits.txt
+          fi
+
+      - name: Bump version and write changelog
+        if: steps.check.outputs.changed == 'true'
+        run: |
+          BUMP="${{ inputs.bump || 'patch' }}"
+          OLD="${{ steps.check.outputs.current }}"
+          NEW=$(node -e "
+            const [maj,min,pat] = '$OLD'.split('.').map(Number);
+            console.log('$BUMP' === 'minor' ? \`\${maj}.\${min+1}.0\` : \`\${maj}.\${min}.\${pat+1}\`);
+          ")
+          echo "Bumping $OLD → $NEW"
+
+          node -e "
+            const fs = require('fs');
+            const p = JSON.parse(fs.readFileSync('package.json','utf8'));
+            p.version = '$NEW';
+            fs.writeFileSync('package.json', JSON.stringify(p,null,2) + '\n');
+          "
+          npm install --package-lock-only --ignore-scripts
+
+          # Changelog entry from the commit subjects, so release.yml's notes
+          # extractor (which reads the '## [VERSION]' section) has real content.
+          {
+            echo "## [$NEW] - $(date -u +%Y-%m-%d)"
+            echo
+            echo "Automated weekly release — batches everything merged since \`${{ steps.check.outputs.last_tag }}\`."
+            echo
+            echo "### Changed"
+            echo
+            sed -E 's/^[0-9a-f]+ /- /' /tmp/commits.txt
+            echo
+          } > /tmp/entry.md
+
+          # Splice in directly under '## [Unreleased]'
+          awk '/^## \[Unreleased\]/ { print; print ""; while ((getline line < "/tmp/entry.md") > 0) print line; next } { print }' \
+            CHANGELOG.md > /tmp/CHANGELOG.new && mv /tmp/CHANGELOG.new CHANGELOG.md
+
+          # Keep the spec-kit extension metadata in lockstep (same thing
+          # `docguard fix --write` does locally before a manual release).
+          node cli/docguard.mjs fix --write || true
+
+          echo "NEW_VERSION=$NEW" >> "$GITHUB_ENV"
+
+      - name: Verify the tree is still green before releasing
+        if: steps.check.outputs.changed == 'true'
+        run: |
+          npm ci
+          npm test
+          node cli/docguard.mjs guard || [ $? -eq 2 ]
+
+      - name: Commit and push (this triggers release.yml)
+        if: steps.check.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add package.json package-lock.json CHANGELOG.md extensions/ .agent/ 2>/dev/null || true
+          git commit -m "release: v${NEW_VERSION} — automated weekly batch
+
+          Cut by .github/workflows/scheduled-release.yml. Publishing itself is
+          handled by release.yml, which triggers on this package.json change."
+          git push origin HEAD:main

{docguard_cli-0.34.2 → docguard_cli-0.34.4}/.wolf/anatomy.md

@@ -1,7 +1,7 @@
 # anatomy.md
 
-> Auto-maintained by OpenWolf. Last scanned: 2026-09-11T14:49:52.100Z
-> Files: 704 tracked | Anatomy hits: 0 | Misses: 0
+> Auto-maintained by OpenWolf. Last scanned: 2026-09-11T15:34:41.013Z
+> Files: 707 tracked | Anatomy hits: 0 | Misses: 0
 
 ## ../../../../../../../tmp/
 
@@ -29,7 +29,7 @@
 - `.pre-commit-hooks.yaml` — DocGuard hooks for the pre-commit framework (https://pre-commit.com). (~490 tok)
 - `action.yml` — Declares fs (~7591 tok)
 - `AGENTS.md` — AI Agent Instructions — DocGuard (~1827 tok)
-- `CHANGELOG.md` — Changelog (~51473 tok)
+- `CHANGELOG.md` — Changelog (~52543 tok)
 - `CLAUDE.md` — OpenWolf (~57 tok)
 - `CODE_OF_CONDUCT.md` — Contributor Covenant Code of Conduct (~532 tok)
 - `COMPARISONS.md` — Comparisons & Honest Limitations (~3382 tok)
@@ -959,8 +959,11 @@
 
 ## .github/workflows/
 
-- `ci.yml` — CI: DocGuard CI (~1468 tok)
-- `release.yml` — CI: Auto Release — Tag, GitHub Release, npm, PyPI (~3434 tok)
+- `auto-merge.yml` — CI: Auto-merge (green bot PRs) (~1917 tok)
+- `ci.yml` — CI: DocGuard CI (~1843 tok)
+- `jules-triage.yml` — CI: Jules PR Triage (~1635 tok)
+- `release.yml` — CI: Auto Release — Tag, GitHub Release, npm, PyPI (~4258 tok)
+- `scheduled-release.yml` — CI: Scheduled Release (~1539 tok)
 - `sync-speckit-catalog.yml` — CI: Prepare Spec Kit Catalog Submission (Manual) (~1385 tok)
 
 ## .jules/

{docguard_cli-0.34.2 → docguard_cli-0.34.4}/.wolf/buglog.json

@@ -4450,6 +4450,180 @@
       "occurrences": 3,
       "last_seen": "2026-09-11T14:34:00Z",
       "notes": "Do NOT keep blindly retrying publish-npm if this recurs after a token rotation looks successful — verify the token's actual publish scope/expiration on npmjs.com first. Also: don't assume '404 on a publish that should be an update' is a transient registry blip just because npm's status page is green and the error text sounds like a missing-package error — check secret rotation dates before concluding 'try again later'."
+    },
+    {
+      "id": "bug-270",
+      "timestamp": "2026-09-11T15:15:53.416Z",
+      "error_message": "Significant refactor of ",
+      "file": ".github/workflows/release.yml",
+      "root_cause": "2 lines replaced/restructured",
+      "fix": "Rewrote 10→18 lines (2 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "yml"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:15:53.416Z"
+    },
+    {
+      "id": "bug-271",
+      "timestamp": "2026-09-11T15:17:16.971Z",
+      "error_message": "Incorrect value in code",
+      "file": "package.json",
+      "root_cause": "Had \"0.34.2\"",
+      "fix": "Changed to \"0.34.3\"",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "json"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:17:16.971Z"
+    },
+    {
+      "id": "bug-257",
+      "timestamp": "2026-09-11T15:20:00Z",
+      "error_message": "Resolution of bug-256 (expired NPM_TOKEN blocking publish-npm for 2 releases).",
+      "file": ".github/workflows/release.yml",
+      "root_cause": "See bug-256: a stored GitHub secret (NPM_TOKEN) with an ~90-day expiration window, no rotation reminder, silent failure mode (npm returns 404 not 401/403 on the auth-scope failure). Structural problem: ANY stored long-lived publish credential recurs this exact class of outage eventually.",
+      "fix": "Migrated publish-npm from NODE_AUTH_TOKEN (classic token auth) to npm Trusted Publishing (OIDC) — configured a trusted publisher on npmjs.com for docguard-cli (GitHub Actions, raccioly/docguard, release.yml, 'Allow npm publish' enabled since the workflow does a direct publish not stage+publish), then removed NODE_AUTH_TOKEN from the workflow entirely and added `npm install -g npm@latest` before publish (Trusted Publishing needs npm CLI >=11.5.0; Node 20's bundled npm predates that). The existing `id-token: write` permission (already present for provenance signing) is reused for the OIDC exchange itself — no new permissions needed. Nothing in this setup can expire the way a stored token did; npm mints a short-lived token per run. Verified end-to-end with a real v0.34.3 release (no code changes, purely to exercise the new pipeline — a rerun of the OLD failed job would have used the stale pre-fix workflow file, since GitHub Actions reruns pin to the original run's commit).",
+      "tags": [
+        "npm-publish",
+        "trusted-publishing",
+        "oidc",
+        "release-pipeline",
+        "permanent-fix",
+        "browser-automation"
+      ],
+      "related_bugs": [
+        "bug-256"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:20:00Z",
+      "notes": "The npm-side setup (trusted publisher config) was done via Claude in Chrome browser automation on the user's authenticated session — the user generated nothing themselves manually beyond confirming form field values live, since a different browser extension's autofill overlay blocked automation from reaching two fields directly. Token/credential VALUES never passed through the agent's context at any point — only the trusted-publisher CONFIGURATION (org/repo/workflow name, which are not secrets) did."
+    },
+    {
+      "id": "bug-273",
+      "timestamp": "2026-09-11T15:25:25.069Z",
+      "error_message": "Significant refactor of ",
+      "file": ".github/workflows/release.yml",
+      "root_cause": "8 lines replaced/restructured",
+      "fix": "Rewrote 9→16 lines (8 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "yml"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:25:25.069Z"
+    },
+    {
+      "id": "bug-274",
+      "timestamp": "2026-09-11T15:26:38.465Z",
+      "error_message": "Significant refactor of ",
+      "file": "CHANGELOG.md",
+      "root_cause": "3 lines replaced/restructured",
+      "fix": "Rewrote 10→18 lines (3 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "md"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:26:38.465Z"
+    },
+    {
+      "id": "bug-275",
+      "timestamp": "2026-09-11T15:26:43.072Z",
+      "error_message": "Incorrect value in code",
+      "file": "package.json",
+      "root_cause": "Had \"0.34.3\"",
+      "fix": "Changed to \"0.34.4\"",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "json"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:26:43.072Z"
+    },
+    {
+      "id": "bug-258",
+      "timestamp": "2026-09-11T15:28:00Z",
+      "error_message": "v0.34.3's own npm-publish fix (Trusted Publishing) failed on its first real test: 'npm install -g npm@latest' errored EBADENGINE, npm@12.0.2 requires node ^22.22.2 || ^24.15.0 || >=26.0.0, actual was npm 10.8.2 / node v20.20.2.",
+      "file": ".github/workflows/release.yml",
+      "root_cause": "Same class of mistake as bug-255 (@babel/parser major bump breaking Node 18): an unpinned `npm@latest` in the publish-npm job's self-update step floated to npm 12, which had bumped ITS OWN Node engine floor past the Node 20 this job runs on. The bug shipped in v0.34.3 because it wasn't (couldn't be) tested locally — GitHub Actions' OIDC token exchange only exists inside an actual Actions run, so the self-update step's own compatibility was the first thing to actually execute in CI, and it failed before publish ever ran.",
+      "fix": "Pinned to `npm install -g npm@11` instead of `npm@latest`. npm 11.x declares engines {node: '^20.17.0 || >=22.9.0'}, compatible with the job's Node 20.20.2, and resolves to 11.19.1 -- well past the 11.5.0 floor Trusted Publishing needs. Verified locally this time: installed npm@11 into an isolated --prefix on Node 20.20.2 (matching the exact runner version from the failure log) and confirmed it resolves cleanly before pushing v0.34.4.",
+      "tags": [
+        "npm-publish",
+        "trusted-publishing",
+        "engines-field",
+        "unpinned-latest",
+        "release-pipeline",
+        "same-mistake-twice"
+      ],
+      "related_bugs": [
+        "bug-256",
+        "bug-257",
+        "bug-255"
+      ],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:28:00Z",
+      "notes": "Pattern worth internalizing: 'npm install -g npm@latest' (or any @latest) in a CI step pinned to an older Node version is never safe to assume works, because npm's OWN major versions bump their engines floor over time just like any other package. Always pin to a specific major/range you've checked against the job's actual Node version, and verify by actually installing it (even in an isolated prefix) rather than reasoning from memory about what should be compatible."
+    },
+    {
+      "id": "bug-277",
+      "timestamp": "2026-09-11T15:31:51.639Z",
+      "error_message": "Missing error handling in unknown",
+      "file": ".github/workflows/ci.yml",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "yml"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:31:51.639Z"
+    },
+    {
+      "id": "bug-278",
+      "timestamp": "2026-09-11T15:33:55.369Z",
+      "error_message": "Missing error handling in unknown",
+      "file": ".github/workflows/jules-triage.yml",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "yml"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:33:55.369Z"
+    },
+    {
+      "id": "bug-279",
+      "timestamp": "2026-09-11T15:34:41.023Z",
+      "error_message": "Missing error handling in unknown",
+      "file": "CHANGELOG.md",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "md"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T15:34:41.023Z"
     }
   ]
 }