docguard-cli 0.36.2__tar.gz → 0.37.1__tar.gz

docguard_cli-0.37.1/.agent/architect.md

@@ -0,0 +1,84 @@
+# Architecture Decision Journal
+
+## 2026-09-14 — Spec lifecycle authority and context retirement
+
+**Problem:** Completed feature folders and superseded plans remain beside active
+requirements. Agents can interpret historical prose as current intent, while
+direct implementation changes may never flow back into specs.
+
+**Evidence:** Spec Kit deliberately supports flow-back, flow-forward, and living
+spec persistence models rather than selecting one. Its extension API exposes
+`before_specify`, `after_implement`, and related lifecycle hooks. The community
+Archive extension consolidates feature deltas into `.specify/memory/`; the
+Reconcile extension updates a feature's artifacts from a bounded drift report.
+Open Spec Kit issue #620 describes the same cross-feature supersession problem.
+
+**Decision:** DocGuard will use a hybrid living-contract model:
+
+1. Active approved requirement prose remains the source of intent.
+2. Source, configuration, and tests remain implementation evidence.
+3. `.docguard-specs.json` becomes a deterministic, committed control plane.
+   Reviewed fields are authoritative for orthogonal approval, delivery, context,
+   storage, persistence policy, lineage, and declared scope;
+   generated fields index requirement identities, evidence, and reconciliation
+   revision. It points to requirement prose and does not copy it.
+4. Context packs are generated projections of active registry entries and
+   canonical docs.
+5. Completed/superseded prose leaves active search paths after consolidation;
+   Git plus `.docguard-archive.json` preserve recovery and provenance.
+6. DocGuard validates compatible Archive/Reconcile extension outputs instead of
+   recreating their prompt-based merge workflows.
+7. Completion is a delivery transition from `implemented → verified`. Checked tasks
+   establish a claim; reconciliation of intent, tests, implementation evidence,
+   and current docs establishes verification.
+8. A verified spec receives a bounded outcome record before its historical prose
+   leaves active context. Direct code changes either refresh proven mechanical
+   facts or create a reviewed amendment/successor decision.
+9. Spec identity comes from immutable metadata, not its directory. Requirement
+   evidence uses `specId#requirementId`; retired IDs remain as tombstones so a
+   bare `FR-001` can never rebind and certify another feature.
+10. `.docguard-archive.json` owns generic document recovery events, while
+    `.docguard-specs.json` owns spec governance. A validator cross-checks both;
+    neither duplicates retired prose.
+11. One `docguard specs` command family is the lifecycle-state writer. Guard,
+    trace, preflight, completion, and hooks consume the same pure projection.
+
+**Rejected alternatives:** Keeping every feature folder in the working tree
+preserves audit history but pollutes agent context. Making code automatically
+rewrite requirements can legitimize regressions. Treating the registry as a
+second prose contract creates another drift surface. Contributing a DocGuard
+policy engine directly to Spec Kit core would couple two tools before the
+interoperability contract has field evidence.
+
+**Operational contract:** New-spec preflight refreshes the registry, checks
+identity and lineage, then reports existing implementation evidence, active
+intent conflicts, unreconciled changes, and semantic review items separately.
+Completion regenerates the observed projection and agent context, updates only
+proven mechanical facts automatically, appends the implementation outcome, and
+records the reconciled Git revision. Registry generation is byte-deterministic;
+reviewed control fields survive regeneration.
+
+Registry transitions are atomic across governance and recovery metadata. A
+current spec must resolve to a clean tracked path; a retired spec must resolve to
+a matching retained recovery event; supersession must name an approved current
+successor; verification must carry exact revision and requirement-qualified
+evidence.
+
+Preflight has two points: an advisory briefing before a spec exists and an
+enforceable structural check after specification but before planning. Spec Kit
+hooks can prompt these actions, while CLI/CI owns the blocking result. DocGuard
+refreshes only its own context outputs and validates compatible extension
+outputs; it does not silently rewrite agent-native instruction files.
+
+**Lifecycle representation:** Do not overload one `status`. Approval
+(`draft|approved|rejected`), delivery
+(`planned|in_progress|implemented|verified|released`), context
+(`current|retired`), retirement reason (`completed|superseded|abandoned`),
+storage (`working_tree|git_history`), and persistence policy are independent.
+Archive readiness is stricter than implementation verification because the
+source revision and every live backreference must also remain valid.
+
+**Upstream path:** Prove the registry and hooks in DocGuard, interoperate with the
+existing community extensions, then propose a generic lifecycle metadata/hook
+contract on Spec Kit issue #620. Keep DocGuard-specific evidence and enforcement
+outside Spec Kit core.

{docguard_cli-0.36.2/extensions/spec-kit-docguard → docguard_cli-0.37.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.36.2
+  version: 0.37.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.36.2 -->
+<!-- docguard:version: 0.37.1 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.36.2 → docguard_cli-0.37.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.35.0
+  version: 0.37.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.35.0 -->
+<!-- docguard:version: 0.37.1 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.36.2/extensions/spec-kit-docguard → docguard_cli-0.37.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.36.2
+  version: 0.37.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.36.2 -->
+<!-- docguard:version: 0.37.1 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.36.2/extensions/spec-kit-docguard → docguard_cli-0.37.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.36.2
+  version: 0.37.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.36.2 -->
+<!-- docguard:version: 0.37.1 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.36.2 → docguard_cli-0.37.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.35.0
+  version: 0.37.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.35.0 -->
+<!-- docguard:version: 0.37.1 -->
 
 # DocGuard Sync Skill
 

docguard_cli-0.37.1/.docguard-archive.json

@@ -0,0 +1,170 @@
+{
+  "schemaVersion": 1,
+  "strategy": "git-history",
+  "retention": {
+    "ref": "refs/remotes/origin/main",
+    "objectFormat": "sha1",
+    "recoverability": "verified"
+  },
+  "entries": [
+    {
+      "path": "docs-canonical/SURFACE-AUDIT.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "a2ba5ab7e6fc4cd6f5893b4584f57a6146749550",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- docs-canonical/SURFACE-AUDIT.md"
+    },
+    {
+      "path": "docs-implementation/MIGRATION-v0.20.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "400a4a62adc0a9d63b968635811ab5e59369c8d6",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- docs-implementation/MIGRATION-v0.20.md"
+    },
+    {
+      "path": "docs-implementation/OSS-PRECISION-ASSESSMENT.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "d08f940514deeb2db0aa4c06519c2a7d5c2dd4fc",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- docs-implementation/OSS-PRECISION-ASSESSMENT.md"
+    },
+    {
+      "path": "docs-implementation/PRECISION-VALIDATION.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "af0b34a37834be34669d5d4a1398820f2f75575f",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- docs-implementation/PRECISION-VALIDATION.md"
+    },
+    {
+      "path": "docs-implementation/TRUST-ROADMAP.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "3bae2edd854413283b99074ae024f187b29ec263",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- docs-implementation/TRUST-ROADMAP.md"
+    },
+    {
+      "path": "docs-implementation/TRUST-VALIDATION.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "e5df37fcd648f7d6ae86a1e6941371bf0319882d",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- docs-implementation/TRUST-VALIDATION.md"
+    },
+    {
+      "path": "specs/001-fix-ignore-validators/plan.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "83ad7c749e4847a9d922403836e37ec4e93904c6",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/001-fix-ignore-validators/plan.md"
+    },
+    {
+      "path": "specs/001-fix-ignore-validators/spec.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "1bd554afadfb95c014a4510946ce70b8c80a8a55",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "requirementIds": [
+        "FR-001", "FR-002", "FR-003", "FR-004", "FR-005", "FR-006", "FR-007",
+        "FR-008", "FR-009", "FR-010", "FR-011", "FR-012", "FR-013", "FR-014",
+        "SC-001", "SC-002", "SC-003", "SC-004", "SC-005", "SC-006"
+      ],
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/001-fix-ignore-validators/spec.md"
+    },
+    {
+      "path": "specs/001-fix-ignore-validators/tasks.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "db1030e5d20e67ab905e9a25bad92d24cfd9fe8e",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "requirementIds": [
+        "T001", "T002", "T003", "T004", "T005", "T006", "T007", "T008", "T009",
+        "T010", "T011", "T012", "T013", "T014", "T015", "T016", "T017", "T018", "T019"
+      ],
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/001-fix-ignore-validators/tasks.md"
+    },
+    {
+      "path": "specs/002-fix-test-discovery/plan.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "5f8d5ff9a49ec3be89c6a1b5432410696ef85d6d",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/002-fix-test-discovery/plan.md"
+    },
+    {
+      "path": "specs/002-fix-test-discovery/spec.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "93f087a13b3fca5a03f237cfb7909f71f15da9b2",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "requirementIds": [
+        "FR-001", "FR-002", "FR-003", "FR-004", "FR-005", "FR-006", "FR-007", "FR-008",
+        "SC-001", "SC-002", "SC-003", "SC-004", "SC-005"
+      ],
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/002-fix-test-discovery/spec.md"
+    },
+    {
+      "path": "specs/002-fix-test-discovery/tasks.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "dbf69eac7f5c5113c5a1034fb01ebcf5275f9857",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "requirementIds": [
+        "T001", "T002", "T003", "T004", "T005", "T006", "T007",
+        "T008", "T009", "T010", "T011", "T012", "T013", "T014"
+      ],
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/002-fix-test-discovery/tasks.md"
+    },
+    {
+      "path": "specs/003-v011-false-positives/plan.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "ffbc773ffca6bd889cb342b048093cf2a9bebde6",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/003-v011-false-positives/plan.md"
+    },
+    {
+      "path": "specs/003-v011-false-positives/spec.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "99c99ab6ad8e83398eafaee4a8605eb1481d2bef",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "requirementIds": [
+        "FR-001", "FR-002", "FR-003", "FR-004", "FR-005", "FR-006", "FR-007", "FR-008",
+        "FR-009", "FR-010", "FR-011", "FR-012", "FR-013", "FR-014", "FR-015", "FR-016",
+        "SC-001", "SC-002", "SC-003", "SC-004", "SC-005", "SC-006", "SC-007", "SC-008",
+        "SC-009", "SC-010"
+      ],
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/003-v011-false-positives/spec.md"
+    },
+    {
+      "path": "specs/003-v011-false-positives/tasks.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "9ac9f4931e360d81756891140ef0bf72ce7b15c0",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/003-v011-false-positives/tasks.md"
+    },
+    {
+      "path": "specs/004-v020-env-var-false-negative/spec.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "36d1fa4855fa68c33f9d73765206d85d7d2268df",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/004-v020-env-var-false-negative/spec.md"
+    },
+    {
+      "path": "specs/005-hugocross-next-bugs/spec.md",
+      "archivedAt": "2026-09-14T15:26:57.257Z",
+      "archivedFrom": "b921dcbd0cc3476594100a414e3f8e9d4daa39c8",
+      "blob": "ef774e226a55710a95f49d2ee3e066db86dedf2d",
+      "reason": "Released or superseded work; current behavior is represented by canonical docs, tests, and CHANGELOG.md",
+      "restore": "git restore --source=b921dcbd0cc3476594100a414e3f8e9d4daa39c8 -- specs/005-hugocross-next-bugs/spec.md"
+    }
+  ]
+}