docguard-cli 0.10.0 → 0.11.1

package/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.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Fix Skill
 
@@ -36,9 +36,19 @@ Research the actual codebase to generate or repair canonical documentation that
 
 ## Execution Flow
 
+### Step 0: Apply Mechanical Fixes First (no AI needed)
+
+```bash
+npx docguard-cli fix --write 2>&1
+```
+
+Removes endpoints documented in `docs-canonical/API-REFERENCE.md` that the OpenAPI
+spec confirms no longer exist (table row + detail block). Only edits
+`docguard:generated` docs, idempotent, prints what changed. Don't hand-edit these.
+
 ### Step 1: Diagnose Current State
 
-Run the diagnostic to identify all issues:
+Run the diagnostic to identify all issues (each tagged `mechanical` or `agent`):
 
 ```bash
 npx docguard-cli diagnose 2>&1

package/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.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Guard Skill
 

package/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.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Review Skill
 

package/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.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: docguard-sync
+description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-truth doc sections in place (mechanical, idempotent, preserves human prose) and flags the prose sections you must review when code changes.
+compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
+metadata:
+  author: docguard
+  version: 0.11.1
+  source: extensions/spec-kit-docguard/skills/docguard-sync
+---
+
+# DocGuard Sync Skill
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input. If `--since <ref>` is provided, include the
+git diff context in your reasoning when reviewing prose sections.
+
+## Goal
+
+When code changes, re-derive the code-truth surface (endpoints, entities,
+screens, tech stack, env vars), refresh the matching `<!-- docguard:section
+source=code -->` blocks in canonical docs in place, and **review/refresh the
+human-written prose** in the same docs so it still describes reality.
+
+## Operating Constraints
+
+- **Mechanical refreshes do not need you.** DocGuard does them itself. Your job
+  is the prose sections flagged as "review" — where the human writing may no
+  longer match the new code reality.
+- **Never edit anything outside the marked `source=human` sections** in
+  generated docs. The markers protect human writing; respect them.
+- **Use the dry run first** to see what will change before applying.
+
+## Execution Flow
+
+### Step 1 — Preview what's stale
+
+```bash
+npx --yes docguard-cli@latest sync 2>&1
+```
+
+Reads:
+- `↻` / `•` lines: code-truth sections that drifted (you don't need to write these).
+- `🤖 Prose to review` lines: human-written sections whose surrounding code changed — **these are yours**.
+
+### Step 2 — Apply the mechanical refresh
+
+```bash
+npx --yes docguard-cli@latest sync --write 2>&1
+```
+
+Re-derives every code-truth section from the current code and rewrites only those
+markers. Idempotent — running again is a no-op when up to date.
+
+### Step 3 — Review the flagged prose
+
+For each `🤖 Prose to review` entry:
+
+1. Open the doc (e.g. `docs-canonical/API-REFERENCE.md`).
+2. Locate the `<!-- docguard:section id=<id> source=human -->` block.
+3. **Read the surrounding `source=code` section first** — that's the new truth
+   (e.g. the refreshed endpoint list, the refreshed screens table).
+4. Update the human prose so it still accurately describes that truth.
+   Examples of what to update:
+   - The API overview's endpoint count, or its description of the surface area.
+   - The Architecture overview when new components/services appeared.
+   - The Screens flows when new screens were added/removed/renamed.
+5. Stay inside the `source=human` markers — don't touch the code sections.
+
+### Step 4 — Verify
+
+```bash
+npx --yes docguard-cli@latest guard
+```
+
+Confirm there are no errors. If the API surface drifted (`API-Surface` failures),
+combine with `docguard fix --write` (the mechanical removal of stale endpoints).
+
+### Step 5 — Loop
+
+The intended flow is `sync → guard → (fix if needed) → guard → commit`. Run sync
+again before opening a PR to make sure the memory is current.
+
+## What to do if `--since <ref>` is provided
+
+When `--since main` is given, DocGuard also lists the changed code files since
+that ref. Use that diff to:
+
+- Prioritize which prose sections to update first (the ones whose related code
+  files changed most).
+- Cite concrete change reasons in your prose updates ("Added `/api/orders`
+  endpoint in commit X" → update the API overview accordingly).
+
+## Common patterns
+
+| Symptom | Action |
+|---|---|
+| `↻ docs-canonical/API-REFERENCE.md → endpoints` | Code-truth refreshed by `--write`. No action needed. |
+| `🤖 docs-canonical/API-REFERENCE.md → overview` | Open the doc; update the `overview` prose to reflect the new endpoint set. |
+| `Skipped … not marked docguard:generated` | The doc isn't owned by DocGuard. Either add the marker (and commit ownership) or skip with `--force`. |
+| `Documentation memory is up to date` | Done — no drift. |
+
+## Anti-patterns (do NOT do these)
+
+- ❌ Editing inside `<!-- docguard:section source=code -->` — DocGuard will rewrite it on the next sync.
+- ❌ 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.

package/package.json

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

package/templates/ARCHITECTURE.md.template

@@ -58,6 +58,58 @@
 |---------|---------|-----|----------|
 | <!-- e.g. Stripe --> | <!-- e.g. Payments --> | <!-- e.g. 99.99% --> | <!-- e.g. Queue + retry --> |
 
+## Infrastructure (IaC)
+
+<!--
+  Skip this section if the project does not use Infrastructure-as-Code.
+  DocGuard auto-detects AWS CDK (cdk.json), Terraform (*.tf), Pulumi
+  (Pulumi.yaml), AWS SAM (template.yaml with AWS::Serverless::), and
+  Serverless Framework (serverless.yml). When any are detected and this
+  section is missing, DocGuard emits ONE consolidated reminder per tool.
+
+  Document the layout for YOUR IaC tool below. Remove the blocks that
+  don't apply.
+-->
+
+### AWS CDK
+
+<!-- Remove this block if you don't use CDK -->
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| App entrypoint | <!-- e.g. packages/cdk/bin/app.ts --> | Instantiates stacks per environment |
+| Stacks | <!-- e.g. packages/cdk/lib/stacks/ --> | One file per CloudFormation stack |
+| Constructs | <!-- e.g. packages/cdk/lib/constructs/ --> | Reusable infrastructure components |
+| Synth config | <!-- e.g. packages/cdk/cdk.json --> | CDK CLI configuration |
+| Context cache | <!-- e.g. packages/cdk/cdk.context.json --> | Environment lookup results (committed) |
+| Synth output | <!-- e.g. packages/cdk/cdk.out/ --> | Generated CloudFormation (gitignored) |
+
+### Terraform
+
+<!-- Remove this block if you don't use Terraform -->
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| Root module | <!-- e.g. infra/*.tf --> | Top-level resources |
+| Reusable modules | <!-- e.g. infra/modules/ --> | Composable infrastructure blocks |
+| Environment configs | <!-- e.g. infra/environments/ --> | Per-env tfvars (dev, staging, prod) |
+| State backend | <!-- e.g. S3 bucket + DynamoDB lock table --> | Remote state storage |
+
+### Pulumi / SAM / Serverless Framework
+
+<!--
+  Document app program (index.ts), stack config, or manifest location.
+  Remove this block if you don't use these tools.
+-->
+
+### Deployment Pipeline
+
+<!-- How does IaC code reach the cloud? -->
+
+- <!-- e.g. PR → CI workflow → terraform plan + manual approval → terraform apply -->
+- <!-- e.g. PR → CodePipeline → cdk deploy → dev/staging/prod -->
+
+
 ## Diagrams
 
 <!-- Architecture diagrams using Mermaid, ASCII art, or linked images -->