docguard-cli 0.41.7__tar.gz → 0.42.1__tar.gz

{docguard_cli-0.41.7/extensions/spec-kit-docguard → docguard_cli-0.42.1/.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.7
+  version: 0.42.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.41.7 -->
+<!-- docguard:version: 0.42.1 -->
 
 # DocGuard Fix Skill
 
@@ -34,6 +34,15 @@ Research the actual codebase to generate or repair canonical documentation that
 - **Maximum 3 validation iterations** — if still failing after 3 rounds, report remaining issues and stop
 - **Research before writing** — understand the codebase first, then generate documentation
 
+## Scope: `act` findings only
+
+Read `disposition` from `docguard guard --format json` before repairing anything.
+
+- **`act`** — DocGuard asserts a defect and names the correction. In scope.
+- **`escalate`** — DocGuard observed a signal and the judgement belongs to a human (freshness history, diff-overlap suspicion, documented-endpoint absence). **Out of scope for this skill.** Report them for review; never edit a document to silence one. A history heuristic saying a review is DUE is not evidence that the document is wrong, and stamping a new review date to clear it destroys the signal without doing the review.
+
+Also read `parserTier`: a finding produced by `regex-fallback` or `fallback-language` came from a pattern match rather than a syntax tree, so verify the underlying source before rewriting a document around it.
+
 ## Execution Flow
 
 ### Step 0: Apply Mechanical Fixes First (no AI needed)

{docguard_cli-0.41.7/extensions/spec-kit-docguard → docguard_cli-0.42.1/.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.7
+  version: 0.42.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.41.7 -->
+<!-- docguard:version: 0.42.1 -->
 
 # DocGuard Guard Skill
 
@@ -24,7 +24,28 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Goal
 
-Execute DocGuard's full guard validator suite against the current project, parse structured results, triage findings by severity and impact, and produce an actionable remediation plan. This skill transforms raw CLI output into an AI-digestible quality assessment.
+Execute DocGuard's full guard validator suite against the current project, parse structured results, triage findings by **disposition and severity**, and produce an actionable remediation plan. This skill transforms raw CLI output into an AI-digestible quality assessment.
+
+### Triage on `disposition` first, severity second
+
+Every finding answers three independent questions. Reading only `severity` conflates them and leads to auto-fixing judgement calls.
+
+| Field | Question | Values |
+|-------|----------|--------|
+| `disposition` | Who decides — the tool or a human? | `act`, `escalate` |
+| `severity` / `effectiveSeverity` | Does CI block? | `error`, `warn`, `info` |
+| `confidence` | How sure is the detector of its **observation**? | `high`, `low` |
+| `evidence.status` | Has the reviewed corpus ever measured this code? | `measured`, `not-measured` |
+| `parserTier` | Which analyzer produced it? | `js-ast`, `py-ast`, `regex-fallback`, `fallback-language`, `mixed`, `not-applicable` |
+
+- **`act`** — DocGuard asserts a defect and names the correction. Safe to apply, including through `/docguard.fix`.
+- **`escalate`** — DocGuard observed a signal; the judgement belongs to the reader. **Never auto-fix these.** Read the source, decide which side is wrong, and say so. FRS002 is the canonical example: the commit count is exact and the finding is `confidence: high`, yet it establishes only that a review is DUE, never that the document is stale.
+
+These axes vary independently. A blocking `error` can be an `escalate`; a `high`-confidence finding can still need a human.
+
+- Read `evidence.status` before trusting a confidence label. `measured` quotes the reviewed corpus with `n` and a Wilson interval; `not-measured` means the label is a maintainer's prior. Most codes are unmeasured — that does not make their findings wrong, only unverified. Report it rather than inflating or discounting the finding.
+- Read `parserTier` when a finding concerns source code. `regex-fallback` or `fallback-language` means no syntax tree was available for that file, so **absence** of a finding there is weak evidence; the owning validator also reports `partial`.
+- Read `checkCoverage` before writing any "all clear". `passed/total` counts checks and its denominator excludes every validator that could not run.
 
 ## Pre-Execution Checks
 
@@ -106,16 +127,19 @@ Output a structured markdown report:
 **Score**: [X]/[Y] checks passed ([percentage]%)
 **Overall Status**: ✅ PASS | ⚠️ WARN | ❌ FAIL
 
+**Work**: [N] to fix · [M] to review
+**Coverage**: [C] of [V] validators checked[, D partial/missing-prerequisite]
+
 ### Summary by Priority
 
-| Priority | Count | Validators Affected |
-|----------|-------|-------------------|
-| CRITICAL | N | [list] |
-| HIGH | N | [list] |
-| MEDIUM | N | [list] |
-| LOW | N | [list] |
+| Priority | Count | To fix | To review | Validators Affected |
+|----------|-------|--------|-----------|-------------------|
+| CRITICAL | N | n | m | [list] |
+| HIGH | N | n | m | [list] |
+| MEDIUM | N | n | m | [list] |
+| LOW | N | n | m | [list] |
 
-### Findings
+### Findings to fix (`disposition: act`)
 
 #### CRITICAL
 1. [Validator]: [Specific issue] → **Fix**: [Exact action to take]
@@ -123,9 +147,17 @@ Output a structured markdown report:
 #### HIGH
 1. [Validator]: [Specific issue] → **Fix**: [Exact action to take]
 
+### Findings to review (`disposition: escalate`)
+
+These need a human judgement; do NOT apply a fix to them.
+
+1. [Validator]: [What DocGuard observed] → **Decide**: [what the reader must determine, and from which source]
+
 [... continue for MEDIUM/LOW only if user requests or total findings < 10]
 ```
 
+When a finding's code is `not-measured`, say so once in the report rather than per finding — it is a fact about DocGuard's benchmark coverage, not about that finding's correctness.
+
 ### Step 5: Remediation Recommendations
 
 For each finding, provide a **specific, actionable fix** — not "fix the issue" but the exact file, section, and content to change:
@@ -140,9 +172,10 @@ For each finding, provide a **specific, actionable fix** — not "fix the issue"
 
 Based on the triage results:
 
-- **If all PASS**: "All configured validators passed. Report declared evidence coverage and any remaining heuristic claims; uncaptured prose is still unverified."
-- **If only MEDIUM/LOW warnings**: "Non-blocking warnings found. Safe to commit, but consider running `/docguard.fix` for automated remediation."
-- **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next."
+- **If all PASS**: "All configured validators passed. [C] of [V] validators were able to check; report declared evidence coverage and any remaining heuristic claims. Uncaptured prose is still unverified."
+- **If only `act` warnings**: "Non-blocking warnings found, all of them things DocGuard can name a correction for. Safe to commit; `/docguard.fix` can remediate them."
+- **If any `escalate` findings**: "[M] finding(s) need a human judgement — DocGuard observed a signal, it did not establish a defect. Review these against the source before changing anything; `/docguard.fix` will NOT resolve them."
+- **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next — for the `act` findings only."
 
 Present the user with options:
 1. "Fix all automatically" → Suggest: `/docguard.fix`
@@ -155,6 +188,8 @@ Present the user with options:
 - **Parse real output** — don't hallucinate check counts or validator names
 - **Be specific** — every fix recommendation must reference an actual file path
 - **Respect severity** — don't escalate LOW to CRITICAL or vice versa
+- **Respect disposition** — never apply an automated fix to an `escalate` finding, and never present one as a defect DocGuard established. Severity says whether CI blocks; disposition says whether a human decides.
+- **Never read absence as proof** — a `no-matches` validator found nothing applicable, a `partial` one could not check everything it was asked to, and a `regex-fallback` tier could not see the whole syntax. Report the gap rather than summarizing it as clean.
 - **Track progress** — if user runs guard multiple times, compare before/after
 - If user provides `$ARGUMENTS` like "just structure" or "only security", filter report to those validators
 

{docguard_cli-0.41.7 → docguard_cli-0.42.1}/.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.7
+  version: 0.42.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.41.7 -->
+<!-- docguard:version: 0.42.1 -->
 
 # DocGuard Review Skill
 
@@ -63,6 +63,25 @@ Record:
 - Category breakdown
 - Exact declared evidence states and the remaining heuristic claim tasks
 
+#### Read the channels before you rank anything
+
+Every finding in `guard --format json` answers four independent questions. This
+skill produces a severity-ranked report, so conflating them puts a signal DocGuard
+never adjudicated at the top of a CRITICAL list.
+
+| Field | Question | Values |
+|-------|----------|--------|
+| `severity` / `effectiveSeverity` | Does CI block? | `error`, `warn`, `info` |
+| `disposition` | Who decides — the tool or a human? | `act`, `escalate` |
+| `confidence` | How sure is the detector of its **observation**? | `high`, `low` |
+| `evidence.status` | Has the reviewed corpus ever measured this code? | `measured`, `not-measured` |
+| `parserTier` | Which analyzer produced it? | `js-ast`, `py-ast`, `regex-fallback`, `fallback-language`, `mixed`, `not-applicable` |
+
+- **`act`** — DocGuard asserts a defect and names the correction. A recommendation may say "change this".
+- **`escalate`** — DocGuard observed a signal; the judgement is the reader's. A recommendation must say "decide this, from this source" — never "change this". FRS002 is the canonical case: the commit count is exact (`confidence: high`) and it establishes only that a review is DUE, never that the document is stale.
+- `not-measured` means the reviewed corpus has never scored this code, so its confidence label is a maintainer's prior. Most codes are unmeasured. Say it once in the report; it is a fact about DocGuard's benchmark coverage, not about these findings being wrong.
+- `regex-fallback` / `fallback-language` means no syntax tree was available for that file. **Absence** of a finding there is weak evidence — never write "no gaps found" over a degraded tier. `diagnose --format json` repeats the same channels per issue, plus a `dispositionCounts` summary.
+
 ### Step 3: Semantic Cross-Document Analysis
 
 This is the **unique value** of the review skill — analysis that CLI validators cannot do.
@@ -124,6 +143,11 @@ Classify every finding using this matrix:
 - **MEDIUM**: Missing cross-reference, minor coverage gap, readability issue
 - **LOW**: Formatting inconsistency, optional section missing, minor terminology drift
 
+Severity is orthogonal to disposition. A CRITICAL finding can still be an
+`escalate` — rank it by impact as usual, then write its recommendation as a
+decision rather than an edit. Carry the disposition into the findings table so a
+reader never has to infer it from the severity column.
+
 ### Step 6: Produce Analysis Report
 
 Output a structured markdown report (do NOT write to disk):
@@ -139,10 +163,11 @@ Output a structured markdown report (do NOT write to disk):
 
 ### Findings Table
 
-| ID | Category | Severity | Location | Summary | Recommendation |
-|----|----------|----------|----------|---------|----------------|
-| R01 | Terminology | HIGH | ARCH:L15, SEC:L22 | "validator" vs "checker" | Standardize on "validator" |
-| R02 | Coverage | MEDIUM | DATA-MODEL.md | Schema X undocumented | Add Schema X to Data Model |
+| ID | Category | Severity | Disposition | Location | Summary | Recommendation |
+|----|----------|----------|-------------|----------|---------|----------------|
+| R01 | Terminology | HIGH | act | ARCH:L15, SEC:L22 | "validator" vs "checker" | Standardize on "validator" |
+| R02 | Coverage | MEDIUM | act | DATA-MODEL.md | Schema X undocumented | Add Schema X to Data Model |
+| R03 | Currency | HIGH | escalate | ARCHITECTURE.md | 13 commits since last review | **Decide**: read `src/` since that date; say whether the component map is now wrong |
 
 ### Per-Document Health
 
@@ -183,6 +208,8 @@ Ask: "Would you like me to fix the top N issues? (I'll show you what I plan to c
 - **Compare actual code vs docs** — don't just validate formatting
 - **Limit findings to 50** — aggregate overflow in a summary count
 - **Prioritize high-signal findings** — one CRITICAL finding is worth ten LOW findings
+- **Respect disposition** — never write an `escalate` finding up as something to change. Severity says whether CI blocks; disposition says who owns the decision. Recommending an edit for a signal DocGuard did not adjudicate destroys the signal and fixes nothing
+- **Never read absence as proof** — a `partial` validator could not check everything it was asked to, and a `regex-fallback` tier could not see the whole syntax. Report the gap instead of summarizing it as clean
 - **Preserve evidence scope** — a verified declaration covers one selected statement, while undeclared prose and whole-document accuracy remain review work
 - **Preserve approved intent** — a contradiction can mean implementation regressed; determine which side owns truth before recommending an edit
 

{docguard_cli-0.41.7 → docguard_cli-0.42.1}/.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.7
+  version: 0.42.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.41.7 -->
+<!-- docguard:version: 0.42.1 -->
 
 # DocGuard Score Skill
 
@@ -95,11 +95,14 @@ Generate an improvement plan ordered by ROI:
 
 ### Step 5: Guard Check Correlation
 
-Cross-reference the score with guard results:
+Cross-reference the score with guard results. Run `guard --format json` (not the
+text output) so each finding's channels are available:
 
 - For each failing guard check, show which score category it impacts
-- Calculate: "If you fix these N guard warnings, score will increase from X to Y"
-- Show the **minimum set of fixes** needed to reach the next grade level
+- **Split the findings on `disposition` before you count points.** `act` findings are correctable and belong in the roadmap. `escalate` findings are signals a human must judge — list them separately, under "decisions pending", with no point value attached. Promising points for clearing an escalation is an instruction to edit a document until a message stops printing, which is exactly the behaviour the channel exists to prevent. Severity does not settle this: a blocking `error` can be an `escalate`.
+- Calculate: "If you fix these N `act` findings, score will increase from X to Y"
+- Show the **minimum set of fixes** needed to reach the next grade level, counting only `act` findings
+- Note any finding whose `parserTier` is `regex-fallback`, `fallback-language` or `mixed`: no syntax tree was available, so the projected gain rests on a pattern match rather than parsed code
 
 ```markdown
 ### Path to Next Grade
@@ -108,9 +111,14 @@ Cross-reference the score with guard results:
 **Next Grade**: A (85/100) — need +7 points
 
 **Minimum fixes for grade A**:
-1. Fix Structure (3 checks failing) → +5 points
-2. Fix Changelog (1 check failing) → +2 points
+1. Fix Structure (3 checks failing, all `act`) → +5 points
+2. Fix Changelog (1 check failing, `act`) → +2 points
 Total effort: ~30 minutes
+
+**Decisions pending (no point value)**:
+- Freshness FRS002 on ARCHITECTURE.md — `escalate`. Read `src/` since the last
+  review date and state whether the component map is now wrong. Leaving it in
+  place after a real review is a correct outcome; guard will still print it.
 ```
 
 ### Step 6: ALCOA+ Compliance Summary
@@ -173,7 +181,9 @@ If user has run score before (check git log for score badge changes):
 - **Be actionable** — every recommendation must have a specific action
 - **Compare before/after** — if user has previously run score in this session, show improvement
 - **Focus on ROI** — surface the cheapest fixes with the biggest score impact first
+- **Never price an escalation** — a finding with `disposition: escalate` gets no projected point gain and never appears in a "minimum fixes" list. It is a decision, not a task. Report it separately and say plainly that it will still print after a correct run
 - **Keep assurance separate** — report `assurance.declaredEvidence` and remaining `unverifiedClaims` beside the structural score; never convert a scoped evidence pass into an accuracy score for a document or project
+- **Score is not accuracy** — the channels make this explicit: a code whose `evidence.status` is `not-measured` has never been scored by the reviewed corpus, so neither its confidence label nor the points attached to clearing it are measured quantities
 
 ## Context
 

{docguard_cli-0.41.7 → docguard_cli-0.42.1}/.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.7
+  version: 0.42.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.41.7 -->
+<!-- docguard:version: 0.42.1 -->
 
 # DocGuard Sync Skill
 
@@ -82,6 +82,18 @@ npx --yes docguard-cli@latest verify --evidence
 Confirm there are no errors. If the API surface drifted (`API-Surface` failures),
 combine with `docguard fix --write` (the mechanical removal of stale endpoints).
 
+**Read the disposition on whatever guard still reports.** Each finding carries
+`disposition: act | escalate` (plus `confidence`, `evidence.status` and
+`parserTier` — see `guard --format json`):
+
+- **`act`** — DocGuard asserts a defect and names the correction. Sync or `fix --write` may clear it.
+- **`escalate`** — DocGuard observed a signal; the judgement is yours. **A sync is not an answer to one.** Rewriting prose, or re-running `sync --write` to move a timestamp, makes the message stop printing without anyone deciding anything. Read the code and the document, decide which side is wrong, and record that decision.
+
+FRS002 is the one you will hit most: "N code commits since the document was
+reviewed" counts commits exactly via `git log`, so it is `confidence: high`, yet
+it establishes only that a review is DUE. Recording a review date you did not
+earn is the failure mode; the timestamp is meant to attest that someone looked.
+
 ### Step 5 — Loop
 
 The intended flow is `sync → guard → (fix if needed) → guard → commit`. Run sync
@@ -106,6 +118,7 @@ that ref. Use that diff to:
 | `Skipped … not marked docguard:generated` | A default-path doc lacks whole-document ownership. Review before using `--force`; a mapped human doc still requires a unique `source=code` section. |
 | `malformed or duplicate docguard:section markers` | Stop. Repair ownership markers explicitly; `--force` cannot authorize the write. |
 | `Documentation memory is up to date` | Done — no drift. |
+| A guard finding with `disposition: escalate` survives the sync | Expected. Judge it and say what you decided; do not sync again to clear it. |
 
 ## Anti-patterns (do NOT do these)
 
@@ -113,3 +126,5 @@ that ref. Use that diff to:
 - ❌ Removing the markers to "make the doc look cleaner" — that breaks future sync/regeneration.
 - ❌ Skipping `sync --write` and editing the code section by hand — let DocGuard do it.
 - ❌ Rewriting an evidence-bound human statement from generated code alone — rerun the declared predicate and review approved intent first.
+- ❌ Treating a `disposition: escalate` finding as drift to sync away — it is a decision someone owes, not a section that is out of date.
+- ❌ Stamping `<!-- docguard:last-reviewed -->` to silence a freshness escalation — the date attests that a human reviewed; writing it without reviewing makes the attestation false.