diff --git a/.agent/skills/docguard-fix/SKILL.md b/.agent/skills/docguard-fix/SKILL.md index 1182199..b1b8e48 100644 --- a/.agent/skills/docguard-fix/SKILL.md +++ b/.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.32.0 + version: 0.33.0 source: extensions/spec-kit-docguard/skills/docguard-fix --- - + # DocGuard Fix Skill diff --git a/.agent/skills/docguard-guard/SKILL.md b/.agent/skills/docguard-guard/SKILL.md index 2564e13..2785033 100644 --- a/.agent/skills/docguard-guard/SKILL.md +++ b/.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.32.0 + version: 0.33.0 source: extensions/spec-kit-docguard/skills/docguard-guard --- - + # DocGuard Guard Skill diff --git a/.agent/skills/docguard-review/SKILL.md b/.agent/skills/docguard-review/SKILL.md index 2d51a2c..bba9be5 100644 --- a/.agent/skills/docguard-review/SKILL.md +++ b/.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.32.0 + version: 0.33.0 source: extensions/spec-kit-docguard/skills/docguard-review --- - + # DocGuard Review Skill diff --git a/.agent/skills/docguard-score/SKILL.md b/.agent/skills/docguard-score/SKILL.md index 218a87b..5dd902a 100644 --- a/.agent/skills/docguard-score/SKILL.md +++ b/.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.32.0 + version: 0.33.0 source: extensions/spec-kit-docguard/skills/docguard-score --- - + # DocGuard Score Skill diff --git a/.agent/skills/docguard-sync/SKILL.md b/.agent/skills/docguard-sync/SKILL.md index 6d44c51..04edf00 100644 --- a/.agent/skills/docguard-sync/SKILL.md +++ b/.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.32.0 + version: 0.33.0 source: extensions/spec-kit-docguard/skills/docguard-sync --- - + # DocGuard Sync Skill diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 20f3f14..de9f3b8 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -158,6 +158,14 @@ jobs: publish-npm: needs: [detect-version, test, create-release] runs-on: ubuntu-latest + # Provenance attestation needs an OIDC token: npm exchanges it with + # Sigstore to sign a statement that THIS tarball was built by THIS + # workflow from THIS commit. That's what supply-chain checks (npm's + # "Provenance" badge, Claude Code's unknown-package legitimacy check, + # socket.dev, etc.) verify — without it the package is unattributable. + permissions: + contents: read + id-token: write steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v6 @@ -165,8 +173,8 @@ jobs: node-version: 20 registry-url: 'https://registry.npmjs.org' - - name: Publish - run: npm publish + - name: Publish (with provenance) + run: npm publish --provenance env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b59fab..26f6383 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- **npm provenance attestation.** Releases now publish with `npm publish --provenance` (OIDC + Sigstore): every tarball carries a signed statement that it was built by this repo's GitHub Actions from a specific commit. This is what "unknown package" legitimacy checks (Claude Code, socket.dev, npm's Provenance badge) verify — DocGuard installs are now cryptographically attributable. +- **PRIVACY.md** — the short, honest policy: DocGuard collects nothing, all analysis is local, no telemetry; the three explicit user-initiated outbound paths (`feedback` URL, `gh`-backed PR commands, opt-in HTTP transport) are enumerated. Ships in the npm package and unblocks Anthropic Connectors Directory submission (a missing privacy policy is an instant rejection there). +- **FAQ**: why AI agents flag DocGuard as "unknown" on first install, and how to pre-trust it (project `.mcp.json`, Always allow, managed-settings allowlist). + ## [0.33.0] - 2026-07-16 ### Added diff --git a/PRIVACY.md b/PRIVACY.md new file mode 100644 index 0000000..6a13b5b --- /dev/null +++ b/PRIVACY.md @@ -0,0 +1,45 @@ +# Privacy Policy — DocGuard + +**Effective: 2026-07-16** + +DocGuard is a local-first command-line tool. This policy is short because the +honest answer is short: **DocGuard collects nothing.** + +## What DocGuard does with your data + +- **All analysis runs locally.** Validators, scoring, reports, the MCP server — + everything reads files on your machine and writes output to your machine. + Nothing is uploaded, sampled, or "improved" with your code or docs. +- **No telemetry, no analytics, no crash reporting.** There is no phone-home + code path. The deterministic core makes no network calls at all. +- **No accounts.** DocGuard has no sign-up, no API keys of its own, and no + server-side component operated by us. + +## The explicit, user-initiated exceptions + +Three commands can *prepare* outbound actions — each is opt-in, visible, and +executed by you or your own tooling, never silently by DocGuard: + +| Command | What happens | +|---------|--------------| +| `docguard feedback` | Builds a **prefilled GitHub issue URL** (redacted and length-capped) and saves a local record. Nothing is sent unless you open the URL and submit it yourself. | +| `docguard upgrade --pr` / `impact --prs` | Shell out to **your** locally-authenticated `gh` CLI to interact with **your** repositories. DocGuard never holds credentials. | +| `docguard mcp --transport http` | Serves read-only tools over HTTP. Binds to loopback by default; binding a non-loopback address **refuses to start** without an `--api-key`. | + +## Data written to disk (yours, locally) + +State lives under `.docguard/` in your repo (fix history, score history, +caches) and `.docguard.baseline.json` if you create one. All of it is plain +text, in your repository, under your version control — delete it any time. + +## Dependencies + +One pinned runtime dependency (`@babel/parser`). The npm package is published +from GitHub Actions with provenance attestation, so you can verify the tarball +was built from this repository. + +## Changes & contact + +Changes to this policy land in this file with a dated entry in +[CHANGELOG.md](CHANGELOG.md). Questions: open an issue at + (see [SUPPORT.md](SUPPORT.md)). diff --git a/README.md b/README.md index 8d1277e..81a76b2 100644 --- a/README.md +++ b/README.md @@ -769,6 +769,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#research--academic-credits) for full citat --- +## 🔒 Privacy & Supply Chain + +DocGuard is local-first: no telemetry, no analytics, no phone-home — the full +(short) policy is in [PRIVACY.md](PRIVACY.md). npm releases are published with +[provenance attestation](https://docs.npmjs.com/generating-provenance-statements), +so you can verify each tarball was built by GitHub Actions from this repository. + ## 📄 License [MIT](LICENSE) — Free to use, modify, and distribute. diff --git a/docs/faq.md b/docs/faq.md index 94725c2..b4bb73d 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -119,6 +119,25 @@ Exit code 0 = pass, 1 = fail. Use `--threshold` to set minimum score. Yes — DocGuard ships a template at `templates/ci/github-actions.yml`. Copy it to `.github/workflows/` or use the reusable action in `action.yml`. +### Claude (or my AI agent) says DocGuard is "unknown" and wants a legitimacy check. Why? + +That's the agent's default posture toward **any** third-party MCP server or +npx package — MCP servers run code with your permissions, so unknown ones get +a trust prompt. It's not a DocGuard-specific flag. What DocGuard provides so +the check can pass: + +- **npm provenance** — releases are signed by GitHub Actions (Sigstore), so + the tarball is verifiably built from this repository. +- **Official MCP registry** — `io.github.raccioly/docguard` is a verified + namespace at registry.modelcontextprotocol.io. +- **Read-only annotations** — every MCP tool declares `readOnlyHint`; the + server never writes or reaches the network. +- **[PRIVACY.md](../PRIVACY.md)** — no telemetry, no data collection. + +To stop the prompt on your own machines: approve with "Always allow", or +pre-trust it for a whole team via a project-scoped `.mcp.json` / +enterprise managed-settings allowlist. + ### Does DocGuard block commits? Only if you install hooks (`docguard hooks`). Without hooks, it's advisory only. diff --git a/package.json b/package.json index 4ead677..e90b2d3 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.", "type": "module", "bin": { - "docguard": "./cli/docguard.mjs" + "docguard": "cli/docguard.mjs" }, "scripts": { "docguard": "node cli/docguard.mjs", @@ -36,7 +36,7 @@ "license": "MIT", "repository": { "type": "git", - "url": "https://github.com/raccioly/docguard" + "url": "git+https://github.com/raccioly/docguard.git" }, "homepage": "https://github.com/raccioly/docguard#readme", "mcpName": "io.github.raccioly/docguard", @@ -57,6 +57,7 @@ "docs/", "schemas/", "STANDARD.md", + "PRIVACY.md", "PHILOSOPHY.md", "README.md", "LICENSE"