docguard-cli 0.37.0 → 0.38.0

package/cli/writers/spec-outcomes.mjs

@@ -0,0 +1,27 @@
+/**
+ * Append a bounded, machine-owned outcome index without rewriting spec intent.
+ * @implements docguard.document-lifecycle#FR-016
+ */
+
+const START = '<!-- docguard:implementation-outcomes:start -->';
+const END = '<!-- docguard:implementation-outcomes:end -->';
+
+function clean(value, max = 500) {
+  return String(value || '').replace(/\s+/g, ' ').replace(/[<>`]/g, '').trim().slice(0, max);
+}
+
+export function appendImplementationOutcome(content, outcome) {
+  const reason = clean(outcome.reason);
+  if (!reason) throw new Error('Implementation outcome requires a non-empty reviewed reason.');
+  const evidence = [...new Set(outcome.evidence || [])].sort().map(path => `\`${path}\``).join(', ') || 'none';
+  const deviations = [...new Set(outcome.deviations || [])].sort().map(item => clean(item)).filter(Boolean).join('; ') || 'none';
+  const successor = outcome.successor ? `\`${outcome.successor}\`` : 'none';
+  const line = `- \`${outcome.revision}\` — ${reason} Evidence: ${evidence}. Accepted deviations: ${deviations}. Successor: ${successor}.`;
+  const block = `${START}\n## Implementation Outcomes\n\n${line}\n${END}`;
+  const pattern = new RegExp(`${START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`);
+  if (!pattern.test(content)) return `${content.trimEnd()}\n\n${block}\n`;
+  const prior = content.match(pattern)?.[0]
+    .split('\n').filter(item => item.startsWith('- `')) || [];
+  const lines = [...prior.filter(item => !item.startsWith(`- \`${outcome.revision}\``)), line].slice(-20);
+  return content.replace(pattern, `${START}\n## Implementation Outcomes\n\n${lines.join('\n')}\n${END}`);
+}

package/extensions/spec-kit-docguard/README.md

@@ -53,6 +53,7 @@ docguard score
 | `speckit.docguard.generate` | — | Reverse-engineer canonical docs from codebase |
 | `speckit.docguard.brief` | — | Load current spec intent before specification |
 | `speckit.docguard.preflight` | — | Gate the generated spec before task generation |
+| `speckit.docguard.complete` | — | Plan reviewed completion and regenerate active context after verification |
 
 ## AI Skills
 
@@ -78,8 +79,11 @@ DocGuard integrates into the spec-kit workflow through hooks:
 hooks:
   before_specify:    # Mandatory — read current spec intent first
     command: speckit.docguard.brief
-  after_implement:   # Mandatory — quality gate after /speckit.implement
-    command: speckit.docguard.guard
+  after_implement:   # Guard is mandatory; completion review is optional
+    - command: speckit.docguard.guard
+    - command: speckit.docguard.complete
+  after_converge:    # Optional completion review after convergence
+    command: speckit.docguard.complete
   before_tasks:      # Mandatory — gate the generated spec
     command: speckit.docguard.preflight
   after_tasks:       # Optional — show score after tasks

package/extensions/spec-kit-docguard/commands/complete.md

@@ -0,0 +1,38 @@
+---
+description: "Review implementation evidence and plan the spec completion transaction"
+allowed-tools: Bash, Read
+---
+
+# DocGuard Spec Completion Review
+
+Run after implementation or convergence. This hook plans the lifecycle gate; it
+does not mark the feature verified without a reviewed rationale.
+
+1. Resolve the current feature `spec.md` and read its `Spec ID` metadata.
+2. Run `docguard guard --format json`. Stop on errors.
+3. Refresh deterministic evidence with `docguard specs --write`, then review and
+   commit that projection with the implementation.
+4. Select the Git baseline that covers the implementation changes. Prefer the
+   registry's prior reconciliation revision; otherwise use the feature branch's
+   merge base with its configured default branch.
+5. Run:
+
+```bash
+docguard specs complete --id <spec-id> --since <ref> --check --format json
+```
+
+6. Review every reconciliation classification. Unsupported or ambiguous changes
+   block completion. A possible implementation regression requires deciding
+   whether to fix code, amend approved intent, or record an accepted deviation.
+7. When the evidence is complete, present the exact reviewed write command to
+   the maintainer. Apply it only when the maintainer supplies the rationale:
+
+```bash
+docguard specs complete --id <spec-id> --since <ref> --write --reason "<reviewed outcome>"
+```
+
+The write records the outcome, advances delivery through `implemented` to
+`verified`, and regenerates `.docguard/current-context.json` as one staged,
+post-validated set. In-process write or validation failures roll the set back;
+the command does not claim a durable journal across power loss or forced
+termination.

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.37.0"
+  version: "0.38.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 5 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"
@@ -57,6 +57,10 @@ provides:
       file: "commands/preflight.md"
       description: "Gate a generated specification against registry integrity and prior intent"
 
+    - name: "speckit.docguard.complete"
+      file: "commands/complete.md"
+      description: "Plan the reviewed implemented-to-verified lifecycle transaction"
+
   # GitHub Actions workflow starters — copyable templates users drop into
   # .github/workflows/ for guard/fix/sync/score integration.
   workflows:
@@ -88,9 +92,21 @@ hooks:
     description: "Load current spec intent and block specification on stale lifecycle state"
 
   after_implement:
-    command: "speckit.docguard.guard"
-    optional: false
-    description: "Quality gate — ensures docs stay in sync with code"
+    - command: "speckit.docguard.guard"
+      optional: false
+      priority: 5
+      description: "Quality gate — ensures docs stay in sync with code"
+    - command: "speckit.docguard.complete"
+      optional: true
+      priority: 10
+      prompt: "Review evidence and plan this spec's completion transaction?"
+      description: "Plan lifecycle verification after implementation"
+
+  after_converge:
+    command: "speckit.docguard.complete"
+    optional: true
+    prompt: "Review evidence and plan this converged spec's completion transaction?"
+    description: "Plan lifecycle verification after convergence"
 
   before_tasks:
     command: "speckit.docguard.preflight"

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.37.0
+  version: 0.38.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.37.0 -->
+<!-- docguard:version: 0.38.0 -->
 
 # DocGuard Fix Skill
 

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.37.0
+  version: 0.38.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.37.0 -->
+<!-- docguard:version: 0.38.0 -->
 
 # 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.37.0
+  version: 0.38.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.37.0 -->
+<!-- docguard:version: 0.38.0 -->
 
 # 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.37.0
+  version: 0.38.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.37.0 -->
+<!-- docguard:version: 0.38.0 -->
 
 # DocGuard Score Skill
 

package/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.37.0
+  version: 0.38.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.37.0 -->
+<!-- docguard:version: 0.38.0 -->
 
 # DocGuard Sync Skill
 

package/extensions/spec-kit-docguard/templates/extensions.yml

@@ -26,6 +26,22 @@ hooks:
       description: "Validate documentation passes CDD standards after implementation"
       enabled: true
       optional: false
+      priority: 5
+    - extension: docguard
+      command: speckit.docguard.complete
+      description: "Plan reviewed lifecycle verification after implementation"
+      enabled: true
+      optional: true
+      priority: 10
+      prompt: "Review evidence and plan this spec's completion transaction?"
+
+  after_converge:
+    - extension: docguard
+      command: speckit.docguard.complete
+      description: "Plan reviewed lifecycle verification after convergence"
+      enabled: true
+      optional: true
+      prompt: "Review evidence and plan this converged spec's completion transaction?"
 
   # Gate the generated spec before /speckit.tasks creates implementation work.
   before_tasks:

package/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.37.0
+        run: npm install --global --ignore-scripts docguard-cli@0.38.0
 
       - name: Run DocGuard
         shell: bash

package/package.json

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

package/schemas/docguard-specs.schema.json

@@ -8,7 +8,7 @@
   "required": ["$schema", "schemaVersion", "specs", "tombstones"],
   "properties": {
     "$schema": { "const": "https://raccioly.github.io/docguard/schemas/docguard-specs.schema.json" },
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "specs": {
       "type": "array",
       "items": { "$ref": "#/definitions/spec" }
@@ -75,13 +75,18 @@
         "reconciliation": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["lastReviewedRevision"],
+          "required": ["lastReviewedRevision", "outcomes"],
           "properties": {
             "lastReviewedRevision": {
               "anyOf": [
                 { "type": "null" },
                 { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" }
               ]
+            },
+            "outcomes": {
+              "type": "array",
+              "maxItems": 20,
+              "items": { "$ref": "#/definitions/outcome" }
             }
           }
         }
@@ -96,6 +101,18 @@
         "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
       }
     },
+    "outcome": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["revision", "reason", "evidence", "deviations", "successor"],
+      "properties": {
+        "revision": { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" },
+        "reason": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "evidence": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1 } },
+        "deviations": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 500 } },
+        "successor": { "anyOf": [{ "type": "null" }, { "$ref": "#/definitions/specId" }] }
+      }
+    },
     "testEvidence": {
       "type": "object",
       "additionalProperties": false,

package/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.37.0
+        run: npm install --global --ignore-scripts docguard-cli@0.38.0
 
       - name: Run DocGuard
         shell: bash