docguard-cli 0.41.6__tar.gz → 0.42.0__tar.gz

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/.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.41.6
+  version: 0.42.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.41.6 -->
+<!-- docguard:version: 0.42.0 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.41.6/extensions/spec-kit-docguard → docguard_cli-0.42.0/.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.41.6
+  version: 0.42.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.41.6 -->
+<!-- docguard:version: 0.42.0 -->
 
 # DocGuard Guard Skill
 

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

{docguard_cli-0.41.6/extensions/spec-kit-docguard → docguard_cli-0.42.0/.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.41.6
+  version: 0.42.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.41.6 -->
+<!-- docguard:version: 0.42.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/.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.41.6
+  version: 0.42.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.41.6 -->
+<!-- docguard:version: 0.42.0 -->
 
 # DocGuard Sync Skill
 

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/.docguard-specs.json

@@ -860,12 +860,12 @@
           {
             "requirementId": "FR-018",
             "file": "tests/hooks-contract.test.mjs",
-            "line": 17
+            "line": 18
           },
           {
             "requirementId": "FR-019",
             "file": "tests/hooks-contract.test.mjs",
-            "line": 18
+            "line": 19
           },
           {
             "requirementId": "FR-020",
@@ -1455,7 +1455,7 @@
           {
             "requirementId": "FR-006",
             "file": "cli/shared-source.mjs",
-            "line": 356
+            "line": 375
           },
           {
             "requirementId": "FR-006",
@@ -1465,7 +1465,7 @@
           {
             "requirementId": "FR-007",
             "file": "cli/shared-source.mjs",
-            "line": 357
+            "line": 376
           },
           {
             "requirementId": "FR-007",
@@ -1853,19 +1853,23 @@
           "docguard.precision-evidence-loop#FR-015",
           "docguard.precision-evidence-loop#FR-016",
           "docguard.precision-evidence-loop#FR-017",
+          "docguard.precision-evidence-loop#FR-018",
+          "docguard.precision-evidence-loop#FR-019",
           "docguard.precision-evidence-loop#SC-001",
           "docguard.precision-evidence-loop#SC-002",
           "docguard.precision-evidence-loop#SC-003",
           "docguard.precision-evidence-loop#SC-004",
           "docguard.precision-evidence-loop#SC-005",
-          "docguard.precision-evidence-loop#SC-006"
+          "docguard.precision-evidence-loop#SC-006",
+          "docguard.precision-evidence-loop#SC-007",
+          "docguard.precision-evidence-loop#SC-008"
         ]
       },
       "observed": {
         "artifacts": [
           {
             "path": "specs/007-precision-evidence-loop/spec.md",
-            "digest": "sha256:5ee5b2e1653b7196ec19755ce2506a79bb8eedc8ccdc72aa8c8672f13912fd8d"
+            "digest": "sha256:2e8c5343cf9ead82f3e5d663da9ba1015e36f9956584edf16d3cc2e0b73fb298"
           },
           {
             "path": "specs/007-precision-evidence-loop/plan.md",
@@ -1873,12 +1877,12 @@
           },
           {
             "path": "specs/007-precision-evidence-loop/tasks.md",
-            "digest": "sha256:f712d9c80309b9a73a3ccdcfad90e3f972810ebbb8c9336e9af951308ece3ec4"
+            "digest": "sha256:f94be4b5d9bb746685a4b832ec6d1d3389b4236b37eb717d92b6cb62d2a6f327"
           }
         ],
         "taskCompletion": {
-          "checked": 19,
-          "total": 19
+          "checked": 28,
+          "total": 28
         },
         "implementationEvidence": [
           {
@@ -1931,11 +1935,26 @@
             "file": "cli/validators/security.mjs",
             "line": 6
           },
+          {
+            "requirementId": "FR-004",
+            "file": "benchmarks/fixtures/python-layered-control/src/models/order.py",
+            "line": 1
+          },
+          {
+            "requirementId": "FR-004",
+            "file": "benchmarks/fixtures/python-layered-control/src/services/order_service.py",
+            "line": 1
+          },
           {
             "requirementId": "FR-004",
             "file": "benchmarks/lib/manifest.mjs",
             "line": 6
           },
+          {
+            "requirementId": "FR-005",
+            "file": "benchmarks/fixtures/python-layered-control/src/routes/orders.py",
+            "line": 1
+          },
           {
             "requirementId": "FR-005",
             "file": "benchmarks/lib/manifest.mjs",
@@ -1971,6 +1990,11 @@
             "file": "benchmarks/lib/manifest.mjs",
             "line": 8
           },
+          {
+            "requirementId": "FR-009",
+            "file": "benchmarks/lib/baseline.mjs",
+            "line": 6
+          },
           {
             "requirementId": "FR-009",
             "file": "benchmarks/lib/compare.mjs",
@@ -2025,6 +2049,26 @@
             "requirementId": "FR-017",
             "file": "benchmarks/lib/runner.mjs",
             "line": 6
+          },
+          {
+            "requirementId": "FR-018",
+            "file": "benchmarks/lib/baseline.mjs",
+            "line": 7
+          },
+          {
+            "requirementId": "FR-019",
+            "file": "benchmarks/generate-precision-evidence.mjs",
+            "line": 10
+          },
+          {
+            "requirementId": "FR-019",
+            "file": "benchmarks/lib/precision-evidence.mjs",
+            "line": 12
+          },
+          {
+            "requirementId": "FR-019",
+            "file": "cli/precision-evidence.mjs",
+            "line": 11
           }
         ],
         "testEvidence": [
@@ -2078,6 +2122,11 @@
             "file": "tests/benchmark-manifest.test.mjs",
             "line": 11
           },
+          {
+            "requirementId": "FR-009",
+            "file": "tests/benchmark-baseline.test.mjs",
+            "line": 9
+          },
           {
             "requirementId": "FR-009",
             "file": "tests/benchmark-metrics.test.mjs",
@@ -2133,6 +2182,16 @@
             "file": "tests/benchmark-runner.test.mjs",
             "line": 11
           },
+          {
+            "requirementId": "FR-018",
+            "file": "tests/benchmark-baseline.test.mjs",
+            "line": 10
+          },
+          {
+            "requirementId": "FR-019",
+            "file": "tests/precision-evidence.test.mjs",
+            "line": 8
+          },
           {
             "requirementId": "SC-001",
             "file": "tests/benchmark-manifest.test.mjs",
@@ -2158,6 +2217,11 @@
             "file": "tests/benchmark-runner.test.mjs",
             "line": 13
           },
+          {
+            "requirementId": "SC-005",
+            "file": "tests/benchmark-baseline.test.mjs",
+            "line": 11
+          },
           {
             "requirementId": "SC-005",
             "file": "tests/benchmark-manifest.test.mjs",
@@ -2167,6 +2231,16 @@
             "requirementId": "SC-006",
             "file": "tests/feedback-fixture.test.mjs",
             "line": 15
+          },
+          {
+            "requirementId": "SC-007",
+            "file": "tests/benchmark-baseline.test.mjs",
+            "line": 12
+          },
+          {
+            "requirementId": "SC-008",
+            "file": "tests/precision-evidence.test.mjs",
+            "line": 9
           }
         ]
       }

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/.github/workflows/ci.yml

@@ -128,6 +128,11 @@ jobs:
           head -5 /tmp/report.md
           node cli/docguard.mjs report --format json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['integrity'].startswith('sha256:'), d; print('report json OK', d['integrity'][:20])"
 
+      - name: Precision benchmark (network-free corpus vs reviewed baseline)
+        run: |
+          node benchmarks/run.mjs --baseline benchmarks/baseline.json > /tmp/benchmark.json
+          node -e "const r=require('/tmp/benchmark.json'); console.log('benchmark', r.comparison.core.status, 'measures:', r.provenance.measures, '| out of selection:', r.comparison.core.outOfSelection.length); if (r.comparison.core.status !== 'PASS') process.exit(1)"
+
       - name: Guard JUnit output is valid XML
         run: |
           node cli/docguard.mjs guard --format junit > /tmp/guard-junit.xml || [ $? -eq 2 ]

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/.github/workflows/scheduled-release.yml

@@ -135,6 +135,19 @@ jobs:
           # The extension skills are authoritative. Refresh their checked-in
           # `.agent` copies before the parity test and release commit.
           node --input-type=module -e "import { ensureSkills } from './cli/ensure-skills.mjs'; ensureSkills(process.cwd(), { format: 'json', noSpecKit: true });"
+          # DELIBERATELY NOT REGENERATED HERE: llms.txt / llms-full.txt.
+          # tests/llms-bundle-drift.test.mjs already fails any pull request that
+          # changes a canonical or optional document without running
+          # `npm run llms`, so every section except the inlined changelog body is
+          # current on main at all times. Regenerating them in THIS job bought
+          # only a footer version stamp and the spliced release header, and cost
+          # two outages: the paths were not in RELEASE_PATH_ALLOWLIST (which
+          # failed the v0.42.0 cut outright), and a wholesale-regenerated file
+          # has no line-level ancestor, so any pull request merged while this
+          # release PR waits for approval conflicts hard and forces a recut.
+          # The footer is a provenance record — "generated by the version that
+          # generated it" is true; restamping it from a job that regenerates
+          # nothing else is not.
 
           echo "NEW_VERSION=$NEW" >> "$GITHUB_ENV"
 

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/AGENTS.md

@@ -1,6 +1,6 @@
 # AI Agent Instructions — DocGuard
 
-<!-- docguard:last-reviewed 2026-09-15 -->
+<!-- docguard:last-reviewed 2026-09-18 -->
 
 > This project follows **Canonical-Driven Development (CDD)**.
 > Documentation is the source of truth. Read before coding.
@@ -66,7 +66,9 @@ config/CLI), `watch` (live re-guard).
 ## Consuming Guard Output (agents)
 
 Prefer the machine contract over parsing prose: `docguard guard --format json`
-returns `status` (PASS/WARN/FAIL, matches exit code 0/2/1), `findings[]`
+returns `status` (PASS/WARN/FAIL, matches exit code 0/2/1 — but FAIL exits `3`,
+not `1`, when the project has no `.docguard.json`, so branch on `status` rather
+than assuming `1`), `findings[]`
 (`{code, severity, confidence, message, location, suggestion}`), `nextStep`,
 `reportable[]` (low-confidence findings — verify before acting), `coverage`
 (Markdown tier map incl. `unclassified[]`), `evidence`, and `semanticClaims.count`

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/CHANGELOG.md

@@ -7,6 +7,289 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **The release cut no longer regenerates `llms.txt` / `llms-full.txt`.** Adding
+  that step bought a footer version stamp and the spliced release header, and
+  cost two outages in one evening. The paths were not in
+  `RELEASE_PATH_ALLOWLIST`, which failed the v0.42.0 cut outright before it
+  opened a PR; and because a wholesale-regenerated file has no line-level common
+  ancestor, any pull request merged while the release PR waits for its approval
+  conflicts hard and forces the release to be recut. `CHANGELOG.md` never had
+  this problem — it auto-merges — so the bundles introduced a genuinely new
+  conflict class rather than another instance of an old one.
+  `tests/llms-bundle-drift.test.mjs` already fails any pull request that changes
+  a canonical or optional document without running `npm run llms`, so every
+  section except the inlined changelog body is current on `main` at all times;
+  the release job was only ever covering that one exempted body.
+  The allowlist now refuses the two paths again, and the release job is asserted
+  neither to run the regeneration nor to stage the files, so the outage cannot
+  return by someone re-admitting them to make a failing cut pass.
+  Consequence, stated plainly: a published `llms-full.txt` carries its changelog
+  entries under `## [Unreleased]` rather than under the version header it ships
+  with. The entries are all present — only the header is not — and the footer
+  now truthfully records the version that generated the bundle instead of being
+  restamped by a job that regenerated nothing else.
+
+
+## [0.42.0] - 2026-09-18
+
+Automated weekly release — batches everything merged since `v0.41.7`.
+
+### Changed
+
+- docs: review ENVIRONMENT.md, completing the freshness pass (#431)
+- fix: let the release cut include the llms bundles it regenerates (#430)
+- chore: consolidate the Unreleased changelog into one section per kind (#429)
+- chore: regenerate llms.txt / llms-full.txt and keep them from rotting (#424)
+- docs: freshness review of the nine docs stamped 2026-09-15 (#426)
+- fix: init no longer adopts a feature folder and then refuses its own config (#427)
+- test(benchmark): measure ARC001 — the architecture validator's first evidence (#428)
+- feat: tell the reader whether a finding's detector has ever been benchmarked (#423)
+- feat: say what the benchmark measures — provenance envelope, honest wording, CI-run recipe (#422)
+- test: add missing tests for shared-git.mjs functions (#421)
+
+
+### Added
+
+- `ENVIRONMENT.md` now lists `npm run llms` under Development and the shipped
+  GitLab CI component under CI/CD. Both were missing: the drift test added with
+  the llms bundles names `npm run llms` in its failure message, so a contributor
+  who edits a canonical document meets that command with nothing in the
+  environment doc to explain it, and `templates/ci/gitlab-component.yml` ships
+  beside the Actions workflow but only the latter was shown.
+
+- **The architecture validator has benchmark evidence for the first time.** A
+  new `synthetic-python-layers` pair measures ARC001 on a statically analysable
+  three-layer Python package: the clean control routes every call
+  `routes -> services -> models`, and the defect makes the route layer import
+  the model layer directly, bypassing the declared service boundary. This is
+  what the static Python import-graph support added after 0.38.0 made possible;
+  before it, the only architecture case in the corpus was a dynamic import the
+  analyzer cannot see. `docguard explain ARC001` now reports measured evidence
+  instead of `not-measured`. Its denominator is 1, below the reporting floor of
+  5, so it publishes counts and a Wilson interval (20.7%-100%) and backs off to
+  the whole-corpus tier rather than quoting a rate of its own.
+
+- **Findings now say whether they have ever been benchmarked.** `guard`
+  results carry a `precisionEvidence` block scoped to the finding codes that
+  run emitted, `guard`'s summary reports how many of them have measured
+  precision, and `docguard explain <CODE>` prints the evidence in prose.
+  DocGuard defines 104 finding codes and its reviewed corpus measures 7, so for
+  most codes the honest answer is "never benchmarked" — and that is now stated
+  rather than left for a reader to discover. A code never inherits the measured
+  precision of other codes in its validator; a measured code with fewer than
+  five labelled findings behind it quotes no point estimate on its own and may
+  fall back to a named coarser tier. Contract:
+  `schemas/docguard-precision-evidence.schema.json`. Findings themselves are
+  unchanged, so SARIF, JUnit, baselines and feedback records are unaffected.
+- `npm run generate:precision-evidence` projects the reviewed baseline into
+  `cli/precision-evidence-data.mjs`, which ships with the package because
+  `benchmarks/` deliberately does not. A test fails on drift.
+
+### Changed
+
+- **`ENVIRONMENT.md` reviewed against the code, completing the freshness pass.**
+  It was the one canonical document still on an older marker, and it crossed the
+  10-commit review threshold. Every claim was checked against
+  `cli/commands/mcp.mjs` and holds: the HTTP MCP server binds `127.0.0.1` by
+  default, refuses a non-loopback host without a key, lets `--api-key` take
+  precedence over `DOCGUARD_API_KEY`, and answers `401` without a matching
+  `Authorization: Bearer` or `X-API-Key` header. No correction was needed, so the
+  marker bump is the review record rather than a cosmetic refresh.
+
+- **Published benchmark aggregates moved**, because two labelled cases entered
+  the corpus: 12 defect/12 control pairs across 12 repository groups became
+  13/13 across 13. Precision and recall stay 1.0 with zero false positives; the
+  Wilson 95% lower bound on precision rises from 75.7% to 77.2% on the larger
+  denominator, and the unsupported rate falls from 4.0% to 3.7%. The
+  `architecture` detector and the `py-ast` parser tier move from a null
+  precision (no measured cases) to 1.0 with a 20.7% lower bound. The reviewed
+  baseline and `cli/precision-evidence-data.mjs` were regenerated together.
+  Note that `review.limitations` already claimed seven measured finding codes
+  while `byCode` carried six; it counted ARC001, which the data reported as
+  `not-measured`. The count is now accurate rather than aspirational.
+
+- **The reviewed benchmark was re-run in full on the current release.** It had
+  last run on 0.38.0 while the tool was at 0.41.7, so the evidence now quoted
+  at finding time would have been four releases stale. The re-run, including
+  the five pinned public repositories, compares PASS with zero regressions and
+  byte-identical metrics. One case moved: the Python architecture case is now
+  `checked` rather than `unsupported`, because the analyzer gained Python
+  import-graph support after 0.38.0. It stays classified `unsupported_syntax`
+  and excluded from every ratio pending re-adjudication.
+
+- **Canonical docs reviewed against the code, not just re-stamped.** All nine
+  documents carrying a `last-reviewed 2026-09-15` marker were read against the 14
+  commits that landed since, and four carried real drift:
+  - `ARCHITECTURE.md` stated the project as `~24K lines across cli/`. That figure
+    was written on 2026-05-29, when `cli/` held 21.7K lines; it is 39.4K today, so
+    it had survived several reviews. It now states the measurement date and the
+    command to reproduce it.
+  - Guard's exit code `3` (errors in a project with no `.docguard.json`) shipped
+    with the hook fail-open fix and was documented nowhere. `ARCHITECTURE.md` had
+    `0 | 1 | 2` in two places, and `AGENTS.md` told agents `status` "matches exit
+    code 0/2/1" — which silently misleads any agent branching on `1` for FAIL.
+    Both now record `3`, and `CI-RECIPES.md` explains why a repo-wide hook lets an
+    unadopted working tree commit.
+  - `SECURITY.md`'s command-safety table gained the foreign-hook backup boundary:
+    `--force` skips a foreign hook and writes no `.bak`, so overwriting one takes
+    `--force` twice, not a plain re-install.
+  - `DATA-MODEL.md` now describes name-based document discovery — normalised
+    filenames matched against per-role aliases, a two-role minimum before a
+    directory counts as canonical, and the removal of the accidental
+    macOS/Linux difference that literal-path probing produced.
+  - New `FR-018` records the uninitialised-project hook boundary, which shipped
+    with `tests/hook-fail-open.test.mjs` but no stated requirement.
+
+  `TEST-SPEC.md`, `REQUIREMENTS.md`, `ROADMAP.md` and `CLAUDE.md` were verified
+  accurate and carry a marker bump only. Checked and found correct: every test
+  file cited across the canonical set exists; the benchmark claim of "24 measured
+  cases across 12 repository groups plus one explicit unsupported case" matches
+  `benchmarks/baseline.json` exactly; the validator count (29) is right. The
+  "15 commands" that `verify --semantic` flags in `TEST-SPEC.md` sits in a
+  historical revision row from 2026-03-13 and is deliberately left alone.
+
+- **`llms.txt` stopped claiming DocGuard is "v0.6".** The footer quoted
+  `config.version` — the `.docguard.json` *schema* version — so every generated
+  `llms.txt`, in every adopting project, announced the config format version as
+  though it were the tool version. Both forms now stamp the real release, and
+  `llms-full.txt` carries it too (it previously carried no version at all). The
+  tool version is now one exported `TOOL_VERSION` in `cli/shared.mjs`, read from
+  the package manifest, replacing the entrypoint's private copy — so a release
+  bump cannot leave a stale literal anywhere.
+- **`llms.txt` and `llms-full.txt` are regenerated, and stay that way.** Both
+  bundles ship inside the npm and PyPI tarballs, so an agent reads them as this
+  project's own account of itself — and neither had been regenerated since
+  v0.37.0. The full form was still describing a `guard --format json` contract
+  that predated `evidence`, `specs preflight`, `reconcile` and `agent --task`.
+  Every inlined section was verified byte-for-byte against its source doc.
+  Three things now keep them current: `npm run llms` (`tools/generate-llms.mjs`),
+  a regeneration step in the weekly release workflow — run after the changelog
+  splice, so a published bundle describes the version being released — and
+  `tests/llms-bundle-drift.test.mjs`, which fails CI when a canonical or
+  optional doc changes without the bundles being rebuilt.
+  The drift test deliberately exempts the inlined `CHANGELOG.md` body: it is
+  capped at 400 lines from the top and this repo requires a changelog entry on
+  every commit, so gating it byte-exact would fail every pull request. Release-
+  time regeneration covers that body instead.
+- `generateLlmsTxt` and `generateLlmsFullTxt` now share one exported
+  `llmsDocSet()` instead of duplicating doc discovery, so the index form and the
+  full form cannot disagree about which docs a project has. Output is unchanged,
+  byte-for-byte.
+
+- **The benchmark now says what its numbers are.** `benchmarks/baseline.json`
+  is a strict provenance envelope (`schemas/docguard-benchmark-baseline.schema.json`,
+  envelope `schemaVersion` 2): `review.measures` is `benchmark-precision` and
+  `review.caveat` is the sentence that must accompany any quoted ratio — both
+  derived from the retained cases, and re-verified on load together with every
+  metric, so a hand-edited precision figure or a stale caveat is rejected instead
+  of published. Every `benchmarks/run.mjs` report carries the same
+  `provenance` block whether or not it is persisted. The baseline is validated
+  *before* the run starts.
+- **Wording.** PHILOSOPHY, README, CONTRIBUTING, and the `diagnose` command no
+  longer call the HIGH/MEDIUM/LOW labels "calibrated": they are deterministic
+  strata that borrow TRACE's vocabulary. What is measured — detector precision
+  on a balanced labelled corpus, with n and Wilson bounds — is now linked from
+  each of those places, and VALIDATION.md quotes the numbers with their caveat.
+  DocGuard deliberately does not emit a calibration document: a balanced corpus
+  has no base rate to calibrate against.
+- **Breaking for the benchmark tool only** (the CLI is unaffected): a baseline
+  written by `--write-baseline` before this release (envelope `schemaVersion` 1)
+  is refused with instructions to regenerate it after review.
+
+### Fixed
+
+- **The release cut was rejected by its own path allowlist.** `scheduled-release.yml`
+  regenerates `llms.txt` and `llms-full.txt` inside the release job, but the
+  privileged-PR allowlist in `cli/release-pr-policy.mjs` did not admit them, so
+  validation failed with `paths: unexpected llms-full.txt, llms.txt` and no
+  release could be cut. Both are deterministic output of the repository, like the
+  other generated artifacts already on the list.
+
+- **`init` no longer adopts a Spec Kit feature folder as the project's canonical
+  root, then refuses to proceed from the config it just wrote.** A repository
+  with `specs/002-some-feature/spec.md` and `data-model.md` had that single
+  feature directory adopted, a two-key `.docguard.json` written, and init then
+  threw from its own mapped-layout guard. Every re-run repeated it, by a second
+  code path, so the project could not be initialized without editing the config
+  by hand. Three things were wrong and all three are fixed:
+  - A numbered feature directory (`specs/003-slug/`) is no longer an adoption
+    candidate. It holds one feature's paperwork, not the project's documentation.
+  - Adopting a layout no longer aborts init. The guard that forbids generating
+    INTO a mapped document stays, but init now simply scaffolds the roles the
+    mapping has not placed, so it neither writes into a mapped document nor
+    creates a duplicate beside it. `setup`, `init --wizard` and `diagnose --auto`
+    still generate whole documents and still honour the guard.
+  - Adoption no longer writes `.docguard.json` itself. init owns the single
+    write, so a failed run leaves nothing behind and an adopted layout gets a
+    complete config with its profile, project type and validators, instead of a
+    two-key fragment that short-circuited the real one.
+  The guard's message now names the mapped roles and says how to leave the state.
+- **A Cloudflare Worker is typed `api` again, not `library`.** `init` and `setup`
+  each carried a private copy of project-type detection, and neither had learned
+  about Workers, so `needsEnvVars`, `needsEnvExample`, `needsE2E` and
+  `needsDatabase` were all set wrong and the validators that matter most for a
+  Worker were silently disabled. All three copies are now one exported function
+  (`wrangler.toml`, `wrangler.json` and `wrangler.jsonc` were already all
+  recognised there), and a test fails if a private copy reappears.
+- A detected Playwright or Cypress config, or an `e2e`/`tests/e2e` directory, now
+  sets `needsE2E` regardless of the project type's default. A suite on disk is
+  evidence; the type default is only a guess.
+
+
+
+- The documented network-free recipe `node benchmarks/run.mjs --baseline
+  benchmarks/baseline.json` failed with ten spurious `case-removed` regressions
+  because the comparator did not know the run had not selected the pinned
+  public cases. The runner now reports its `selection`, the comparator lists
+  unselected baseline cases under `outOfSelection`, and CI runs the recipe on
+  every push.
+
+## [0.41.7] - 2026-09-18
+
+Automated weekly release — batches everything merged since `v0.41.6`.
+
+### Changed
+
+- feat: detect documents by name across the codebase, not by exact path (#418)
+
+
+### Added
+
+- Find the documents a project already has, instead of assuming where they are.
+  `init` now looks for canonical role filenames across the repository before
+  creating anything, reports what it found, and offers to adopt that location —
+  writing both `docs.roles` and a matching `requiredFiles.canonical`. Detection
+  recognises real-world spellings rather than one exact filename: separators and
+  case are ignored (`data_model.md`, `Data Model.md`), `.markdown` and `.mdx`
+  count, and each role has known aliases (`system-design.md`, `testing.md`,
+  `env.md`, `api.md`, `PRD.md`). A directory must hold at least two roles before
+  it qualifies, so a lone root `SECURITY.md` — GitHub's policy file — never
+  triggers relocation, and the conventional directory wins any tie.
+
+### Fixed
+
+- Judge the same repository the same way on every platform. Three detectors
+  probed for literal filenames — `existsSync(resolve(dir, 'ROADMAP.md'))` — which
+  matches `roadmap.md` on a case-insensitive filesystem (macOS) and not on a
+  case-sensitive one (Linux). CI and a laptop could therefore disagree about
+  whether the same TODO was tracked. Matching is now explicitly case- and
+  separator-insensitive, decided by DocGuard rather than by the filesystem.
+- Recognise work-tracking documents by name rather than by exact path. A TODO
+  recorded in `docs/ROADMAP.md`, `PLAN.md` or `TASKS.md` was reported as
+  untracked because only ten literal paths were consulted. Tracking documents
+  are now found by alias across the conventional documentation directories;
+  `README.md` and `NOTES.md` still do not count as work lists.
+- Recognise test directories beyond four exact names. `testing/`, `e2e/`,
+  `integration/`, `specs/` and `Tests/` now satisfy the same signal as `tests/`.
+- Stop scaffolding a second canonical directory next to an existing one.
+  A project keeping its documents in `docs/canonical/` read as empty, because
+  the first-run check only walked `docs-canonical/`. `init` then reported "no
+  canonical docs", offered to reverse-engineer them from code, and created a
+  duplicate set beside the real documents. Reported as #326.
+
+
 ## [0.41.6] - 2026-09-18
 
 Automated weekly release — batches everything merged since `v0.41.5`.

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- docguard:last-reviewed 2026-09-15 -->
+<!-- docguard:last-reviewed 2026-09-18 -->
 
 # OpenWolf
 

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/CONTRIBUTING.md

@@ -166,7 +166,7 @@ The following papers directly influenced DocGuard's design:
 
 | DocGuard Feature | Research Origin | Paper |
 |-----------------|----------------|-------|
-| Quality labels (HIGH/MED/LOW) in `guard` output | CJE quality stratification | TRACE [2] |
+| Quality labels (HIGH/MED/LOW) in `guard` output — label vocabulary only; the labels are deterministic strata, not calibrated probabilities (see PHILOSOPHY.md) | CJE quality stratification | TRACE [2] |
 | Standards citations in generated docs | RAG-grounded standards alignment | AITPG [1] |
 | Multi-signal composite scoring in `score` | 5-signal weighted composite (Eq. 1) | TRACE [2] |
 | Traceability matrix (`trace` command) | Requirements traceability | AITPG [1] |
@@ -189,6 +189,7 @@ A report or a test-only contribution is useful even when you cannot fix the dete
 4. Set `provenance.synthetic` and `redactionAttested` only after reviewing every inline file. Record the parser tier, exact expected identity, explicit predicate, same-path opposite control, supported scope, and candidate benchmark delta. The command refuses incomplete contribution evidence.
 5. Generate a direct test with `--contribution tests/<name>.test.mjs`. A false-positive case should stay clean while its neighboring real defect still emits; a missed detection should emit while its clean control remains clean. Ambiguous and policy cases require adjudication before test generation.
 6. Run the focused test and `node benchmarks/run.mjs --external --baseline benchmarks/baseline.json` against the affected version. Describe the result honestly. A test that never exercised the intended parser path is not evidence of a fix.
+7. If the baseline must change, regenerate it with `--write-baseline benchmarks/baseline.json --replace-baseline` and set `review.status`, `reviewedAt`, and `reviewer` by hand after adjudicating every case. Never edit `review.caveat` or `core.metrics`: both are derived from `core.cases` and the loader rejects an envelope where they disagree. When quoting a benchmark number anywhere, quote it with its `n`, its Wilson bound, and the envelope's `review.caveat` — a precision figure without them reads as a calibrated probability, which DocGuard does not measure.
 7. Submit the reviewed example or a test-only PR. Include the duplicate identity so maintainers can find related open and closed work. Follow the repository's changelog and canonical-documentation rules when changing behavior.
 
 Maintainers should acknowledge reproducible reports, preserve contributor attribution with consent, and record the causal defect family in the regression test. Reproduction success and triage time matter more than issue volume. Do not execute arbitrary submitted scripts with repository credentials. Security-sensitive reports belong in the private channel described by SECURITY.md.

{docguard_cli-0.41.6 → docguard_cli-0.42.0}/PHILOSOPHY.md

@@ -113,7 +113,7 @@ generate ──▶ guard ──▶ sync ──▶ guard ──▶ …
 CDD is a practitioner methodology whose patterns align with peer-reviewed research:
 
 - **Generate → validate → evaluate pipeline** — inspired by the AITPG framework (Lopez et al., IEEE TSE 2026): multi-agent generation grounded in standards produces more comprehensive documentation while staying semantically aligned with expert references.
-- **Calibrated quality evaluation** — DocGuard's HIGH/MEDIUM/LOW labels and multi-signal scoring adapt the CJE framework from TRACE (Lopez et al., IEEE TMLCN 2026).
+- **Stratified quality evaluation** — DocGuard's HIGH/MEDIUM/LOW labels and multi-signal scoring adopt the label vocabulary and composite-scoring structure of the CJE framework from TRACE (Lopez et al., IEEE TMLCN 2026). They are deterministic strata (a validator's check pass-ratio, a finding's heuristic confidence tier), not calibrated probabilities: DocGuard has never measured P(finding is real) and does not claim to. What *is* measured is detector precision on a labelled, deliberately balanced benchmark corpus, published with sample sizes and Wilson 95% bounds in [`benchmarks/baseline.json`](benchmarks/baseline.json) and summarised in [VALIDATION.md](VALIDATION.md); every ratio there carries the caveat that benchmark precision on a balanced corpus is not the base rate of stale claims in your repository.
 - **Standards-grounded generation** — each canonical document maps to a relevant standard (arc42, C4, OWASP ASVS, ISO 29119, OpenAPI, 12-Factor App).
 - **Enforcement over instructions** — a 2026 ETH Zurich study (138 repos, 5,694 agent PRs) found the most common style of agent-instruction file *degrades* agent performance; practitioner reports converge on the same conclusion: written rules are routinely ignored, programmatic checks are respected. CDD's answer is to make the docs machine-verified rather than merely machine-readable.