docguard-cli 0.36.0__tar.gz → 0.36.1__tar.gz

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/.wolf/buglog.json

@@ -5110,6 +5110,38 @@
       "related_bugs": [],
       "occurrences": 1,
       "last_seen": "2026-09-11T20:42:23.164Z"
+    },
+    {
+      "id": "bug-311",
+      "timestamp": "2026-09-11T21:26:46.402Z",
+      "error_message": "Published Spec Kit installation displayed an obsolete validator count",
+      "file": "extensions/spec-kit-docguard/extension.yml",
+      "root_cause": "Descriptive metadata and skill prose hardcoded a count outside synchronized documentation checks",
+      "fix": "Remove the hardcoded count from all three extension surfaces and verify the published ZIP after installation",
+      "tags": [
+        "release",
+        "metadata",
+        "documentation"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T21:26:46.402Z"
+    },
+    {
+      "id": "bug-312",
+      "timestamp": "2026-09-11T21:33:22.758Z",
+      "error_message": "Spec Kit verbose helper emitted malformed JSON for current CLI output",
+      "file": "extensions/spec-kit-docguard/scripts/bash/docguard-check-docs.sh",
+      "root_cause": "Legacy regex parsing expected compact score fields and prose guard output; CLI lookup missed installed docguard and did not quote paths",
+      "fix": "Parse and validate structured JSON and exit status; prefer local installs, safely quote executable paths, and refuse implicit npx downloads",
+      "tags": [
+        "release",
+        "json",
+        "hooks"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-09-11T21:33:22.758Z"
     }
   ]
 }

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/.wolf/cerebrum.md

@@ -120,3 +120,5 @@
 - **2026-09-11 (documentation trust)** — Structural score and surface alignment do not establish factual accuracy. Preserve null/unverified across score, CI, report, diagnose, and agent prompts; zero extracted claims does not prove prose correctness. Content-aware plan identity fixes stale uncommitted source results at a measurable hashing cost. Treat fixture strings separately from actual requirement annotations. Public feedback drafts carry registry metadata only; private source context stays local, and submission remains voluntary. `init --with ci` scaffolds a maintained workflow; installing a workflow does not enable branch protection. See docs-implementation/TRUST-ROADMAP.md for researched acceptance gates and deferred empirical work.
 
 - **2026-09-11 (enterprise precision)** — Compare baseline and current on identical disposable source snapshots. Keep originals untouched; concurrent consumer commits are not our changes. A lower warning total is not precision: new review scope can increase findings. OpenAPI absence is not implementation absence. Pair every exception with a true-defect control; source syntax and lexical ownership beat broad line matching. Custom doc roles need both direct-call and CLI write fences. Missing annotations leave behavioral coverage unknown; Python architecture coverage remains explicitly unsupported. Full-suite temp assertions must isolate process-owned fixtures and always clean up with ESM-safe imports. See docs-implementation/PRECISION-VALIDATION.md.
+
+- **2026-09-11 (release verification)** — Install the actual release ZIP in a disposable Spec Kit project before updating the catalog: CLI tests and self-guard did not catch obsolete counts in extension install descriptions. Catalog draft checkboxes are evidence to fill after testing, not automatic assertions. Reuse the existing open submission issue; refresh MCP Registry identity auth when its JWT expires. Preserve published versions and use a patch release for post-publication corrections.

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.36.1] - 2026-09-11
+
+### Fixed
+
+- Removed stale validator counts from the Spec Kit extension installation description, README, and repair skill. Found by installing the published v0.36.0 ZIP in a disposable Spec Kit project. The validation engine is unchanged.
+- The Spec Kit verbose helper reads structured score/guard JSON, preserves PASS/WARN/FAIL, and rejects malformed reports. CLI resolution prefers local installs, quotes paths safely, and requires an installed CLI instead of fetching through npx.
+
+
 ## [0.36.0] - 2026-09-11
 
 ### Fixed

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.36.0
+Version: 0.36.1
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. No Python dependencies (requires Node.js 18+).
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/extensions/spec-kit-docguard/README.md

@@ -1,13 +1,13 @@
 # DocGuard — CDD Enforcement Extension for Spec Kit
 
-Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readable project memory** for [Spec Kit](https://github.com/github/spec-kit). DocGuard builds a complete, language-aware documentation memory of any codebase (`generate --plan`), keeps it always up to date as code changes (`sync`), and verifies it (`guard`) — with deterministic mechanical fixes (`fix --write`) where it can and grounded agent prompts where prose is needed.
+Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readable project memory** for [Spec Kit](https://github.com/github/spec-kit). DocGuard builds source-derived documentation context for supported code (`generate --plan`), refreshes generated sections as code changes (`sync`), and checks configured rules (`guard`) — with deterministic mechanical fixes (`fix --write`) where it can and grounded agent prompts where prose is needed.
 
 ## Features
 
-- **24 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, Cross-Reference, and 13 more
-- **Language-agnostic** — JS/TS, Python, Rust, Go, Java/Kotlin, Ruby, PHP, C#. Polyglot/monorepo-aware.
+- **Configurable validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, Cross-Reference, and more; use `docguard --help` for the current surface
+- **Language-specific extraction** — Supported checks cover several languages and monorepos. Coverage varies by detector; unsupported inputs remain unverified.
 - **AI-powered Generate** — `generate --plan` builds the code-truth skeleton in `<!-- docguard:section -->` markers and emits a structured agent task manifest; the AI writes the prose.
-- **Always up to date** — `sync` surgically refreshes code-truth doc sections in place, **preserves human prose**, flags prose for agent review.
+- **Refresh and review** — `sync` surgically refreshes code-truth doc sections in place, **preserves human prose**, flags prose for agent review.
 - **Mechanical `fix --write`** — deterministic, no-LLM: remove stale documented endpoints, refresh stale "N validators" counts, replace stale version refs, insert missing `## [Unreleased]`.
 - **5 AI Skills** — docguard-fix, docguard-guard, docguard-sync, docguard-review, docguard-score (enterprise-grade behavior protocols, not just step-lists)
 - **Workflow Chaining** — YAML handoffs enable guard → sync → fix → review → score flows
@@ -20,7 +20,7 @@ Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readabl
 npm install -g docguard-cli
 ```
 
-Or use via npx:
+Spec Kit orchestration scripts require a local `node_modules/docguard-cli` installation or `docguard` on PATH; they do not implicitly download a CLI. Direct CLI use via npx remains available:
 ```bash
 npx docguard-cli guard
 ```
@@ -45,7 +45,7 @@ docguard score
 
 | Command | Alias | Purpose |
 |---------|-------|---------|
-| `speckit.docguard.guard` | `docguard.guard` | Run 19-validator quality gate with severity triage |
+| `speckit.docguard.guard` | `docguard.guard` | Run configurable quality gate with severity triage |
 | `speckit.docguard.fix` | `docguard.fix` | AI-driven documentation repair with codebase research |
 | `speckit.docguard.review` | `docguard.review` | Cross-document semantic consistency analysis (read-only) |
 | `speckit.docguard.score` | `docguard.score` | CDD maturity score with ROI improvement roadmap |

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/extensions/spec-kit-docguard/commands/sync.md

@@ -1,5 +1,5 @@
 ---
-description: Keep canonical docs always up to date — refresh code-truth sections in place, preserve human prose
+description: Refresh canonical code-truth sections and flag prose for review — refresh code-truth sections in place, preserve human prose
 allowed-tools: Bash, Read, Edit
 ---
 

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.36.0"
+  version: "0.36.1"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"
@@ -27,7 +27,7 @@ provides:
   commands:
     - name: "speckit.docguard.guard"
       file: "commands/guard.md"
-      description: "Run 19-validator quality gate with severity triage and remediation plan"
+      description: "Run configurable quality gate with severity triage and remediation plan"
 
     - name: "speckit.docguard.fix"
       file: "commands/generate.md"

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/extensions/spec-kit-docguard/scripts/bash/common.sh

@@ -23,25 +23,17 @@ find_docguard_root() {
 
 find_docguard_cli() {
     local root="${1:-$(pwd)}"
-    
-    # Check for local dev mode first
-    if [ -f "$root/cli/docguard.mjs" ]; then
-        echo "node $root/cli/docguard.mjs"
-        return 0
-    fi
-    
-    # Check for global install
-    if command -v docguard-cli >/dev/null 2>&1; then
-        echo "docguard-cli"
-        return 0
-    fi
-    
-    # Fall back to npx
-    if command -v npx >/dev/null 2>&1; then
-        echo "npx docguard-cli"
+    local entry
+    for entry in "$root/cli/docguard.mjs" "$root/node_modules/docguard-cli/cli/docguard.mjs"; do
+        if [ -f "$entry" ] && command -v node >/dev/null 2>&1; then
+            printf '%q %q\n' "$(command -v node)" "$entry"
+            return 0
+        fi
+    done
+    if command -v docguard >/dev/null 2>&1; then
+        printf '%q\n' "$(command -v docguard)"
         return 0
     fi
-    
     return 1
 }
 

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/extensions/spec-kit-docguard/scripts/bash/docguard-check-docs.sh

@@ -104,17 +104,24 @@ if $JSON_MODE; then
     # Optionally include score and guard
     EXTRAS=""
     if $VERBOSE; then
-        SCORE_OUTPUT=$(eval $CLI_CMD score --format json 2>/dev/null || echo "")
-        GUARD_OUTPUT=$(eval $CLI_CMD guard 2>&1 || true)
-        
-        # Extract score
-        SCORE=$(echo "$SCORE_OUTPUT" | grep -o '"total":[0-9]*' | head -1 | sed 's/"total"://' || echo "0")
-        
-        # Extract guard pass/total from output like "156/160 passed"
-        GUARD_PASS=$(echo "$GUARD_OUTPUT" | grep -o '[0-9]*/[0-9]* passed' | sed 's|/.*||' || echo "0")
-        GUARD_TOTAL=$(echo "$GUARD_OUTPUT" | grep -o '[0-9]*/[0-9]* passed' | sed 's|.*/||; s| .*||' || echo "0")
-        
-        EXTRAS=",\"score\":$SCORE,\"guardPass\":$GUARD_PASS,\"guardTotal\":$GUARD_TOTAL"
+        SCORE_OUTPUT=$(eval "$CLI_CMD score --format json")
+        SCORE=$(printf '%s' "$SCORE_OUTPUT" | node -e '
+          const d=JSON.parse(require("fs").readFileSync(0,"utf8"));
+          if(!Number.isFinite(d.score) || d.score<0 || d.score>100) throw Error("Invalid DocGuard score");
+          process.stdout.write(String(d.score));
+        ')
+        GUARD_STATUS=0
+        GUARD_OUTPUT=$(eval "$CLI_CMD guard --format json") || GUARD_STATUS=$?
+        EXTRAS=$(printf '%s' "$GUARD_OUTPUT" | node -e '
+          const d=JSON.parse(require("fs").readFileSync(0,"utf8"));
+          const exit=Number(process.argv[2]);
+          const expected={PASS:0,WARN:2,FAIL:1};
+          if(!Object.hasOwn(expected,d.status) || expected[d.status]!==exit ||
+             !Number.isInteger(d.passed) || !Number.isInteger(d.total) ||
+             d.passed<0 || d.total<d.passed) throw Error("Invalid DocGuard guard report");
+          const fields={score:Number(process.argv[1]),guardPass:d.passed,guardTotal:d.total,guardStatus:d.status};
+          process.stdout.write(","+JSON.stringify(fields).slice(1,-1));
+        ' "$SCORE" "$GUARD_STATUS")
     fi
     
     # Check for spec-kit

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/extensions/spec-kit-docguard/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.36.0
+  version: 0.36.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.36.0 -->
+<!-- docguard:version: 0.36.1 -->
 
 # DocGuard Fix Skill
 
@@ -25,7 +25,7 @@ If no arguments, fix ALL issues found by `docguard diagnose`.
 
 ## Goal
 
-Research the actual codebase to generate or repair canonical documentation that passes DocGuard's 19-validator guard suite. This skill replaces generic templates with real, project-specific content and iterates until quality checks pass.
+Research the actual codebase to generate or repair canonical documentation that passes DocGuard's configurable guard suite. This skill replaces generic templates with real, project-specific content and iterates until quality checks pass.
 
 ## Operating Constraints
 

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

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

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

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

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml

@@ -35,7 +35,7 @@ jobs:
           node-version: '20'
 
       - name: Install DocGuard
-        run: npm install --global --ignore-scripts docguard-cli@0.36.0
+        run: npm install --global --ignore-scripts docguard-cli@0.36.1
 
       - name: Run DocGuard
         shell: bash

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "docguard-cli",
-  "version": "0.36.0",
+  "version": "0.36.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "docguard-cli",
-      "version": "0.36.0",
+      "version": "0.36.1",
       "license": "MIT",
       "dependencies": {
         "@babel/parser": "7.29.8"

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.36.0",
+  "version": "0.36.1",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docguard-cli"
-version = "0.36.0"
+version = "0.36.1"
 description = "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. No Python dependencies (requires Node.js 18+)."
 readme = "README.md"
 license = { text = "MIT" }

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.raccioly/docguard",
   "title": "DocGuard",
   "description": "Deterministic doc-drift detection: guard, score, explain, verify-claims and diagnose MCP tools.",
-  "version": "0.36.0",
+  "version": "0.36.1",
   "websiteUrl": "https://github.com/raccioly/docguard#readme",
   "repository": {
     "url": "https://github.com/raccioly/docguard",
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "docguard-cli",
-      "version": "0.36.0",
+      "version": "0.36.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

{docguard_cli-0.36.0 → docguard_cli-0.36.1}/templates/ci/github-actions.yml

@@ -31,7 +31,7 @@ jobs:
           node-version: '20'
 
       - name: Install DocGuard
-        run: npm install --global --ignore-scripts docguard-cli@0.36.0
+        run: npm install --global --ignore-scripts docguard-cli@0.36.1
 
       - name: Run DocGuard
         shell: bash

docguard_cli-0.36.1/tests/spec-kit-helper-json.test.mjs

@@ -0,0 +1,146 @@
+import { describe, it } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { safeWrite } from '../cli/writers/generate-io.mjs';
+
+const helper = fileURLToPath(new URL('../extensions/spec-kit-docguard/scripts/bash/docguard-check-docs.sh', import.meta.url));
+const scoreJSON = JSON.stringify({ score: 73 }, null, 2);
+const guardJSON = (status = 'PASS', passed = 4, total = 5) => JSON.stringify({ status, passed, total }, null, 2);
+
+// Execute a real Node CLI fixture through the shipped Bash helper. A closed PATH
+// excludes host installs and turns any attempted npx download into a local trap.
+function withProject(options, check) {
+  const temp = realpathSync(mkdtempSync(join(tmpdir(), 'docguard-helper-')));
+  try {
+    const root = join(temp, options.specialPath ? 'project spaces;$(touch INJECTED);\x60touch INJECTED\x60 "quote"' : 'project');
+    const bin = join(temp, 'bin');
+    const calls = join(temp, 'calls.jsonl');
+    mkdirSync(bin);
+    safeWrite(join(root, '.docguard.json'), '{}');
+    symlinkSync(process.execPath, join(bin, 'node'));
+    for (const name of ['dirname', 'basename', 'grep', 'sed', 'tr', 'head', 'cat', 'pwd', 'mktemp', 'rm']) {
+      const executable = ['/usr/bin/', '/bin/'].map(prefix => prefix + name).find(existsSync);
+      assert.ok(executable, name + ' must be available');
+      symlinkSync(executable, join(bin, name));
+    }
+    const fixture = [
+      "import { appendFileSync } from 'node:fs';",
+      'const args = process.argv.slice(2);',
+      'appendFileSync(process.env.CALLS, JSON.stringify({ args, cwd: process.cwd() }) + "\\n");',
+      'if (args.length !== 3 || args[1] !== "--format" || args[2] !== "json") process.exit(91);',
+      'if (args[0] === "score") { process.stdout.write(process.env.SCORE_JSON); process.exit(Number(process.env.SCORE_EXIT)); }',
+      'if (args[0] === "guard") { process.stdout.write(process.env.GUARD_JSON); process.exit(Number(process.env.GUARD_EXIT)); }',
+      'process.exit(92);',
+    ].join('\n');
+    if (options.install !== 'missing') {
+      safeWrite(join(root, options.install === 'package' ? 'node_modules/docguard-cli/cli/docguard.mjs' : 'cli/docguard.mjs'), fixture);
+    }
+    for (const name of ['npx', ...(options.global ? ['docguard', 'docguard-cli'] : [])]) {
+      const executable = join(bin, name);
+      safeWrite(executable, '#!/bin/sh\nprintf "%s\\n" "' + name + '" >> "$TRAPS"\nexit 93\n');
+      chmodSync(executable, 0o755);
+    }
+    const result = spawnSync('/bin/bash', [helper, '--json', '--verbose'], {
+      cwd: root,
+      encoding: 'utf8',
+      timeout: 10000,
+      env: {
+        PATH: bin, HOME: temp, TMPDIR: temp, CALLS: calls, TRAPS: join(temp, 'traps'),
+        SCORE_JSON: scoreJSON, SCORE_EXIT: '0', GUARD_JSON: guardJSON(), GUARD_EXIT: '0',
+        ...options.env,
+      },
+    });
+    assert.equal(result.error, undefined);
+    assert.equal(result.signal, null);
+    assert.equal(existsSync(join(temp, 'traps')), false, 'must not invoke global CLI or npx');
+    assert.equal(existsSync(join(root, 'INJECTED')), false, 'project path must remain literal');
+    assert.equal(existsSync(join(temp, 'INJECTED')), false, 'must not evaluate command substitutions');
+    check(result, root, existsSync(calls) ? readFileSync(calls, 'utf8').trim().split('\n').map(line => JSON.parse(line)) : []);
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+function expectReport(result, root, calls, status) {
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  const report = JSON.parse(result.stdout);
+  assert.equal(report.projectRoot, root);
+  assert.deepEqual({ score: report.score, guardPass: report.guardPass, guardTotal: report.guardTotal, guardStatus: report.guardStatus },
+    { score: 73, guardPass: 4, guardTotal: 5, guardStatus: status });
+  assert.deepEqual(calls, ['score', 'guard'].map(command => ({ args: [command, '--format', 'json'], cwd: root })));
+}
+
+function expectFailure(result) {
+  assert.notEqual(result.status, 0, result.stdout + result.stderr);
+  let report;
+  try { report = JSON.parse(result.stdout); } catch { return; }
+  assert.ok(report && typeof report === 'object' && !Array.isArray(report) && report.error,
+    'failure must not emit a successful helper JSON report: ' + result.stdout);
+  for (const key of ['score', 'guardPass', 'guardTotal', 'guardStatus']) {
+    assert.equal(Object.hasOwn(report, key), false, 'failure must not include success field ' + key);
+  }
+}
+
+describe('Spec Kit helper JSON contract', () => {
+  for (const [status, exit] of [['PASS', 0], ['WARN', 2], ['FAIL', 1]]) {
+    it('reports pretty JSON ' + status + ' with helper exit zero', () => {
+      withProject({ env: { GUARD_JSON: guardJSON(status), GUARD_EXIT: String(exit) } },
+        (result, root, calls) => expectReport(result, root, calls, status));
+    });
+  }
+
+  for (const install of ['dev', 'package']) {
+    it('safely executes ' + install + ' CLI in a path with spaces and shell metacharacters', () => {
+      withProject({ install, specialPath: true }, (result, root, calls) => expectReport(result, root, calls, 'PASS'));
+    });
+  }
+
+  it('prefers installed project package over global executables', () => {
+    withProject({ install: 'package', global: true }, (result, root, calls) => expectReport(result, root, calls, 'PASS'));
+  });
+
+  it('fails without an installed CLI and never falls back to npx', () => {
+    withProject({ install: 'missing' }, (result, root, calls) => {
+      expectFailure(result);
+      assert.deepEqual(calls, []);
+    });
+  });
+
+  for (const value of ['', 'not JSON', '{"score":73', '{"score":73} trailing', '{}', 'null', '[]',
+    '{"score":"73"}', '{"score":null}', '{"score":true}', '{"score":-1}', '{"score":101}', '{"score":1e999}']) {
+    it('rejects invalid score ' + JSON.stringify(value), () => {
+      withProject({ env: { SCORE_JSON: value } }, expectFailure);
+    });
+  }
+
+  const invalidGuards = ['', 'not JSON', '{"status":"PASS","passed":4,"total":5', guardJSON() + ' trailing',
+    '{}', 'null', '[]', '{"status":"PASS","passed":4}', guardJSON('UNKNOWN'), guardJSON('pass'), guardJSON(null)];
+  for (const value of ['4', null, true, -1, 1.5]) {
+    invalidGuards.push(guardJSON('PASS', value, 5), guardJSON('PASS', 0, value));
+  }
+  invalidGuards.push(guardJSON('PASS', 6, 5), '{"status":"PASS","passed":1e999,"total":5}');
+  for (const value of invalidGuards) {
+    it('rejects invalid guard ' + JSON.stringify(value), () => {
+      withProject({ env: { GUARD_JSON: value } }, expectFailure);
+    });
+  }
+
+  for (const [status, validExit] of [['PASS', 0], ['WARN', 2], ['FAIL', 1]]) {
+    for (const exit of [0, 1, 2, 3, 127]) {
+      if (exit === validExit) continue;
+      it('rejects guard status ' + status + ' with exit ' + exit, () => {
+        withProject({ env: { GUARD_JSON: guardJSON(status), GUARD_EXIT: String(exit) } }, expectFailure);
+      });
+    }
+  }
+
+  for (const exit of [1, 2, 127]) {
+    it('rejects valid score JSON when score exits ' + exit, () => {
+      withProject({ env: { SCORE_EXIT: String(exit) } }, expectFailure);
+    });
+  }
+});