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

{docguard_cli-0.34.3/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.3
+  version: 0.34.4
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.34.3 -->
+<!-- docguard:version: 0.34.4 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.34.3 → 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.3/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.3
+  version: 0.34.4
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.34.3 -->
+<!-- docguard:version: 0.34.4 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.34.3/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.3
+  version: 0.34.4
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.34.3 -->
+<!-- docguard:version: 0.34.4 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.34.3 → 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.3 → 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.3 → 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.3 → docguard_cli-0.34.4}/.github/workflows/release.yml

@@ -207,14 +207,21 @@ jobs:
           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. 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@latest
+      # 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

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.3 → docguard_cli-0.34.4}/.wolf/anatomy.md

@@ -1,7 +1,7 @@
 # anatomy.md
 
-> Auto-maintained by OpenWolf. Last scanned: 2026-09-11T15:17:16.962Z
-> 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 (~51752 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 (~4114 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.3 → docguard_cli-0.34.4}/.wolf/buglog.json

@@ -4498,10 +4498,132 @@
         "permanent-fix",
         "browser-automation"
       ],
-      "related_bugs": ["bug-256"],
+      "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"
     }
   ]
 }

{docguard_cli-0.34.3 → docguard_cli-0.34.4}/.wolf/cerebrum.md

@@ -12,6 +12,7 @@
 
 ## Key Learnings
 
+- **2026-09-11 — `npm install -g npm@latest` in a CI step is never safe to assume works — npm's own majors bump their engines floor too.** v0.34.3's Trusted Publishing fix used `npm@latest`, which resolved to npm 12.0.2 (`engines: node ^22.22.2 || ^24.15.0 || >=26.0.0`) — incompatible with the Node 20 the publish-npm job runs on. Exact same class of mistake as bug-255 (@babel/parser major bump), one layer up the toolchain, caught by the pipeline itself on the very next real run. Fix: pin to a checked-compatible range (`npm@11`, whose engines field is `^20.17.0 || >=22.9.0`) and verify by actually installing it in an isolated prefix, not by reasoning about what "should" be compatible. See bug-258.
 - **2026-09-11 — Fixed bug-256 permanently: migrated publish-npm to Trusted Publishing (OIDC), retiring NODE_AUTH_TOKEN entirely.** See bug-257. Two non-obvious things worth remembering: (1) npm Trusted Publishing needs npm CLI >=11.5.0 — Node 20's bundled npm is older, so the workflow now self-updates (`npm install -g npm@latest`) before publishing; forgetting this would trade one failure mode for another. (2) A GitHub Actions "rerun failed jobs" reruns using the workflow file AS IT EXISTED AT THAT RUN'S COMMIT, not the current default-branch version — editing release.yml and then rerunning an old failed run would NOT pick up the fix. Had to cut an actual new release (v0.34.3, no code changes) to get a fresh run that exercises the updated workflow. Confirm any workflow-file fix via a genuinely new run, never a rerun of a run that predates the fix.
 - **2026-09-11 — Claude in Chrome can get blocked by an unrelated browser extension's overlay.** Mid-way through filling an npm settings form (Trusted Publisher setup), clicks and even a plain screenshot started failing with "Cannot access a chrome-extension:// URL of different extension" — almost certainly another extension (password manager autofill is the likely suspect) injected a frame that captured input on the tab. Claude in Chrome can't reach into another extension's frame to dismiss it; the fix was asking the user to click/Escape on their end to clear it, then resuming automation. Also: user's real Chrome profile carries their own extensions, unlike the in-app Browser pane — expect this class of interference there and not in the sandboxed pane.
 - **2026-09-11 — `npm error 404` on a PUBLISH (not install) can mean an expired token, not a missing package or a registry incident.** `publish-npm` for v0.34.1 failed identically 3x over 2 weeks: provenance signs fine (real, distinct Sigstore transparency-log entries each time — proves GitHub's OIDC → Sigstore leg works), then the actual registry PUT 404s with "'docguard-cli@0.34.1' is not in this registry" ~0.1-0.4s later. Ruled out registry incident (npm status green, incident history clean, package untouched on registry each time) before concluding it's the token — `gh secret list` showing `NPM_TOKEN` last rotated 2026-05-22, and the last successful publish being 2026-08-13 (day 83) with every attempt since day 98 failing, lines up with npm's ~90-day Automation-token default expiration. npm apparently returns 404 (not 401/403) for some auth/scope failures on publish, presumably to avoid confirming a package's existence to an unauthorized caller — worth remembering next time a publish 404s on a package that obviously exists. This is NOT fixable by the agent — needs the user to rotate the token on npmjs.com and update the GitHub secret. See bug-256.