gemstack-ai 1.4.0 → 2.0.0

package/specs/013-gemstack-2.0-adaptable-sdd/tasks.md

@@ -0,0 +1,90 @@
+# Tasks Breakdown: Gemstack 2.0 Sprint C — Adaptable SDD & Incremental Specs
+
+**Feature ID:** `013-gemstack-2.0-adaptable-sdd`  
+**Phase:** `tasks`  
+**Parent Release:** `gemstack-ai@2.0.0-alpha`
+
+---
+
+## 1. Inherited Architecture Contracts
+
+```gemstack-contracts
+[
+  {
+    "id": "sdd-rigor-levels",
+    "type": "ENUM_SET",
+    "values": [
+      "quick",
+      "fix",
+      "feature",
+      "high-risk"
+    ]
+  },
+  {
+    "id": "incremental-spec-deltas",
+    "type": "ENUM_SET",
+    "values": [
+      "added",
+      "modified",
+      "removed"
+    ]
+  },
+  {
+    "id": "spec-conflict-detector",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  },
+  {
+    "id": "formal-contract-amendment",
+    "type": "ENUM_SET",
+    "values": [
+      "amendment-id",
+      "contract-id",
+      "version",
+      "reason",
+      "approved-by",
+      "signature"
+    ]
+  }
+]
+```
+
+---
+
+## 2. Task Inventory
+
+- [x] **TASK-001: Author comprehensive test suite for Adaptable SDD**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-RIGOR-A01, TEST-RIGOR-A02, TEST-RIGOR-A03, TEST-RIGOR-A04, TEST-DELTA-B01, TEST-DELTA-B02, TEST-DELTA-B03, TEST-MERGE-C01, TEST-MERGE-C02, TEST-MERGE-C03, TEST-AMEND-D01, TEST-AMEND-D02, TEST-AMEND-D03 -->
+  <!-- gemstack:files=tests/adaptable-sdd-p1.test.js -->
+  <!-- gemstack:depends= -->
+
+- [x] **TASK-002: Implement SDD Rigor Engine**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-RIGOR-A01, TEST-RIGOR-A02, TEST-RIGOR-A03, TEST-RIGOR-A04 -->
+  <!-- gemstack:files=src/lib/sdd-rigor.js -->
+  <!-- gemstack:depends=TASK-001 -->
+
+- [x] **TASK-003: Implement Incremental Spec Engine**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-DELTA-B01, TEST-DELTA-B02, TEST-DELTA-B03 -->
+  <!-- gemstack:files=src/lib/spec-delta.js -->
+  <!-- gemstack:depends=TASK-001 -->
+
+- [x] **TASK-004: Implement Spec Conflict & Merge Engine**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-MERGE-C01, TEST-MERGE-C02, TEST-MERGE-C03 -->
+  <!-- gemstack:files=src/lib/spec-merge.js -->
+  <!-- gemstack:depends=TASK-001 -->
+
+- [x] **TASK-005: Implement Formal Contract Amendment Engine**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-AMEND-D01, TEST-AMEND-D02, TEST-AMEND-D03 -->
+  <!-- gemstack:files=src/lib/contract-amendments.js -->
+  <!-- gemstack:depends=TASK-001 -->
+
+- [x] **TASK-006: Wire CLI commands and verify full CI suite**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-RIGOR-A01, TEST-RIGOR-A02, TEST-RIGOR-A03, TEST-RIGOR-A04, TEST-DELTA-B01, TEST-DELTA-B02, TEST-DELTA-B03, TEST-MERGE-C01, TEST-MERGE-C02, TEST-MERGE-C03, TEST-AMEND-D01, TEST-AMEND-D02, TEST-AMEND-D03 -->
+  <!-- gemstack:files=src/commands/spec.js, src/cli.js, src/commands/verify.js -->
+  <!-- gemstack:depends=TASK-002, TASK-003, TASK-004, TASK-005 -->

package/specs/014-gemstack-2.0-context-memory/.gemstack.json

@@ -0,0 +1,9 @@
+{
+  "phase_hashes": {
+    "spec": "408e0d0aebfc6ac65cb07bbaf694b573571489d2da8aa4314ee7c36d65bbe951",
+    "plan": "845bbb28f699b642f17be9462a3fac71c112d51fb9f23b4b9ad48d665a0f17d2",
+    "tasks": "53c19462e3ec4a7c95c126c0af0fe379ff45f610c32d1bcaad79550b58783a0e"
+  },
+  "historical_findings": [],
+  "accepted_exceptions": []
+}

package/specs/014-gemstack-2.0-context-memory/closure.json

@@ -0,0 +1,58 @@
+{
+  "schema": "gemstack-closure",
+  "version": 1,
+  "feature": "specs/014-gemstack-2.0-context-memory",
+  "generated_at": "2026-09-23T02:09:24.137Z",
+  "status": "VERIFIED",
+  "closure_context": {
+    "closure_context_hash": "8ee2d994f161bb98e4a6724865495ade01b74ed30d8c6c6da42cb0c7db89d40d",
+    "repository_type": "git",
+    "git_commit": "443ae6c7fc8ecfd7ad6f495a2061a8b06de4c386",
+    "working_tree_clean": false,
+    "relevant_files_digest": "04be670b186dee291c30853b4b2e7405bb94859505edf8b6eb786412047801f3"
+  },
+  "acceptance_signature": "9a58e0e0571fac605e964b61a3e4668e895ef35440f7865f65515bf7beafd243",
+  "canonical_summary": {
+    "required_total": 12,
+    "required_passed": 12,
+    "supplemental_total": 0,
+    "supplemental_passed": 0
+  },
+  "physical_summary": {
+    "supporting_total": 0,
+    "supporting_passed": 0,
+    "total_executed": 12,
+    "total_passed": 12,
+    "total_failed": 0,
+    "total_skipped": 0
+  },
+  "reconciliation": {
+    "math_valid": true,
+    "phantoms_detected": 0,
+    "orphans_detected": 0,
+    "missing_canonical_ids": []
+  },
+  "task_traceability_summary": {
+    "tasks_total": 6,
+    "tasks_with_validation": 6,
+    "tasks_documentation_only": 0,
+    "unmapped_canonical_tests": []
+  },
+  "required_gates": {
+    "gate-test": "PASS",
+    "gate-ci-all": "PASS"
+  },
+  "supplemental_gates": {},
+  "exceptions": [],
+  "evidence_sources": [
+    {
+      "type": "PACKAGE_SCRIPT",
+      "script": "test",
+      "runner": "node:test",
+      "exit_code": 0,
+      "duration_ms": 401
+    }
+  ],
+  "blockers": [],
+  "warnings": []
+}

package/specs/014-gemstack-2.0-context-memory/plan.md

@@ -0,0 +1,161 @@
+# Implementation Plan: Gemstack 2.0 Sprint D — Efficient Context & Persistent Memory
+
+**Feature ID:** `014-gemstack-2.0-context-memory`  
+**Phase:** `plan`  
+**Parent Release:** `gemstack-ai@2.0.0-alpha`
+
+---
+
+## 1. Inherited Architecture Contracts
+
+```gemstack-inherited-contracts
+[
+  {
+    "id": "context-fatigue-guard",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  },
+  {
+    "id": "offline-dependency-audit",
+    "type": "ENUM_SET",
+    "values": [
+      "orphan-detector",
+      "undeclared-detector",
+      "circular-cycle-detector",
+      "offline-purity"
+    ]
+  },
+  {
+    "id": "memory-git-cross-audit",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  },
+  {
+    "id": "capsule-noise-elimination",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  }
+]
+```
+
+---
+
+## 2. Technical Architecture & Modules
+
+### 2.1 Context Fatigue & Noise Pruning (`src/lib/context-fatigue.js`)
+- `detectContextFatigue(messages, options)`: Estimates token load, checks against threshold (default 16,000 tokens), computes redundancy ratio, and flags alert.
+- `computeRedundancyRatio(messages)`: Detects duplicate substrings / repetitive prompt outputs.
+- `pruneContextNoise(messages, options)`: Prunes duplicate tool outputs and ephemeral chit-chat while strictly retaining architectural decisions, contract declarations, and active tasks.
+
+### 2.2 Offline Dependency Auditor (`src/lib/dependency-audit.js`)
+- `auditDependencies(targetDir)`:
+  - Scans `package.json` dependencies and devDependencies.
+  - Scans `src/` and other source directories for Node.js `require()` and `import` patterns.
+  - Identifies:
+    - `orphans`: Declared dependencies that are never referenced in code.
+    - `undeclared`: Non-built-in packages imported in code that are missing from `package.json`.
+    - `circularCycles`: Dependency graph cycles using Tarjan's or DFS cycle detection.
+  - 100% offline, zero subprocess execution, zero network requests.
+
+### 2.3 Memory Cross-Audit (`src/lib/memory-audit.js`)
+- `crossAuditMemoryWithGit(targetDir, options)`:
+  - Reads `handoff.md` sections (ensuring Section 4 "Intentos fallidos" is intact).
+  - Fetches recent git log commits (`git log -n 10 --oneline`).
+  - Cross-references commit hashes or keywords against `handoff.md`.
+  - Flags `unrecorded_commits` when recent commits are completely missing from handoff notes.
+
+### 2.4 CLI Integrations
+- Integrate `dependency-audit` into `gemstack doctor` (`src/commands/doctor.js`).
+- Integrate `memory-audit` into `gemstack verify` (`src/commands/verify.js`).
+
+---
+
+## 3. Physical Test Bindings
+
+```gemstack-test-bindings
+[
+  {
+    "id": "TEST-FATIGUE-A01",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Detects context fatigue when accumulated token count exceeds configurable threshold"
+  },
+  {
+    "id": "TEST-FATIGUE-A02",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Identifies repetitive context fragments and computes redundancy ratio accurately"
+  },
+  {
+    "id": "TEST-FATIGUE-A03",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Deterministically prunes noise and duplicate chatter while preserving contracts and state"
+  },
+  {
+    "id": "TEST-DEP-B01",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Detects orphan dependencies declared in package.json but never imported in code"
+  },
+  {
+    "id": "TEST-DEP-B02",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Detects undeclared module dependencies imported in code but missing from package.json"
+  },
+  {
+    "id": "TEST-DEP-B03",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Detects circular import cycles among local project modules"
+  },
+  {
+    "id": "TEST-DEP-B04",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Dependency auditor runs completely offline without spawning npm or network requests"
+  },
+  {
+    "id": "TEST-MEM-C01",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Detects discrepancies between recent git commit messages and handoff.md records"
+  },
+  {
+    "id": "TEST-MEM-C02",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Approves cleanly when all recent commits are accurately reflected in handoff.md"
+  },
+  {
+    "id": "TEST-MEM-C03",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Preserves section 4 Intentos fallidos and flags any attempt to mutate or delete it"
+  },
+  {
+    "id": "TEST-CAPSULE-D01",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Context capsule projection excludes ephemeral conversation logs and noise"
+  },
+  {
+    "id": "TEST-CAPSULE-D02",
+    "file": "tests/context-memory-p1.test.js",
+    "symbol": "Validates capsule determinism and size budget compliance (< 32KB)"
+  }
+]
+```
+
+---
+
+## 4. Mandatory Package Script Closure Gates
+
+```gemstack-closure-gates
+[
+  {
+    "id": "gate-test",
+    "type": "PACKAGE_SCRIPT",
+    "script": "test",
+    "requirement": "REQUIRED",
+    "waivable": false
+  },
+  {
+    "id": "gate-ci-all",
+    "type": "PACKAGE_SCRIPT",
+    "script": "ci:all",
+    "requirement": "REQUIRED",
+    "waivable": false
+  }
+]
+```

package/specs/014-gemstack-2.0-context-memory/spec.md

@@ -0,0 +1,163 @@
+# Specification: Gemstack 2.0 Sprint D — Efficient Context & Persistent Memory
+
+**Feature ID:** `014-gemstack-2.0-context-memory`  
+**Phase:** `spec`  
+**Parent Release:** `gemstack-ai@2.0.0-alpha`
+
+---
+
+## 1. Context & Objectives
+
+As agents and humans collaborate across long-running projects, context management and memory persistence become critical failure points:
+1. **Context Fatigue & Noise**: Agents accumulate thousands of tokens of ephemeral chatter, duplicate error logs, and redundant prompt iterations, degrading reasoning accuracy.
+2. **Dependency Blindness**: Unused or missing dependencies slip into `package.json`, and circular imports create subtle runtime bugs that standard linters miss.
+3. **Memory Drift & Forgotten Commits**: Features get committed to git without being recorded in `handoff.md`, causing context loss across session boundaries.
+
+Sprint D resolves these challenges by introducing:
+- **Context Fatigue Detector & Noise Pruner**: Alerts when context exceeds thresholds or exhibits high redundancy, with deterministic noise pruning.
+- **Offline Dependency Auditor in `gemstack doctor`**: Detects orphan dependencies, undeclared imports, and circular dependencies without external network calls.
+- **Memory Cross-Verification**: Reconciles recent git commits with `handoff.md` before session handoff or verify closure.
+- **Compressed Context Capsule Guard**: Enforces strict exclusion of ephemeral conversation chatter from capsules.
+
+---
+
+## 2. Architecture Contracts
+
+```gemstack-contracts
+[
+  {
+    "id": "context-fatigue-guard",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Monitors accumulated tokens and flags warnings when redundancy ratio or token thresholds are exceeded."
+  },
+  {
+    "id": "offline-dependency-audit",
+    "type": "ENUM_SET",
+    "values": [
+      "orphan-detector",
+      "undeclared-detector",
+      "circular-cycle-detector",
+      "offline-purity"
+    ],
+    "description": "Capabilities of the offline dependency auditor in gemstack doctor."
+  },
+  {
+    "id": "memory-git-cross-audit",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Cross-verifies recent git commit activity against handoff.md before session close."
+  },
+  {
+    "id": "capsule-noise-elimination",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Ensures context capsules strictly exclude chat history and ephemeral noise."
+  }
+]
+```
+
+---
+
+## 3. Mechanical Acceptance Matrix
+
+```gemstack-test-matrix
+[
+  {
+    "id": "TEST-FATIGUE-A01",
+    "category": "CONTEXT",
+    "layer": "UNIT",
+    "description": "Detects context fatigue when accumulated token count exceeds configurable threshold",
+    "pass_criteria": "detectContextFatigue returns fatigue=true and alert message when tokens > limit",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-FATIGUE-A02",
+    "category": "CONTEXT",
+    "layer": "UNIT",
+    "description": "Identifies repetitive context fragments and computes redundancy ratio accurately",
+    "pass_criteria": "computeRedundancyRatio correctly calculates duplicate token ratio",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-FATIGUE-A03",
+    "category": "CONTEXT",
+    "layer": "UNIT",
+    "description": "Deterministically prunes noise and duplicate chatter while preserving contracts and state",
+    "pass_criteria": "pruneContextNoise reduces size while preserving all architectural contracts and state items",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-DEP-B01",
+    "category": "DEPENDENCY",
+    "layer": "UNIT",
+    "description": "Detects orphan dependencies declared in package.json but never imported in code",
+    "pass_criteria": "auditDependencies reports orphan array containing unused dependencies",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-DEP-B02",
+    "category": "DEPENDENCY",
+    "layer": "UNIT",
+    "description": "Detects undeclared module dependencies imported in code but missing from package.json",
+    "pass_criteria": "auditDependencies reports undeclared array containing missing packages",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-DEP-B03",
+    "category": "DEPENDENCY",
+    "layer": "UNIT",
+    "description": "Detects circular import cycles among local project modules",
+    "pass_criteria": "auditDependencies flags circularCycles with the exact cycle path",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-DEP-B04",
+    "category": "DEPENDENCY",
+    "layer": "UNIT",
+    "description": "Dependency auditor runs completely offline without spawning npm or network requests",
+    "pass_criteria": "Runs in <100ms with zero network handles or subprocess calls",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-MEM-C01",
+    "category": "MEMORY",
+    "layer": "UNIT",
+    "description": "Detects discrepancies between recent git commit messages and handoff.md records",
+    "pass_criteria": "crossAuditMemoryWithGit flags unrecorded_commits when commits are missing from handoff",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-MEM-C02",
+    "category": "MEMORY",
+    "layer": "UNIT",
+    "description": "Approves cleanly when all recent commits are accurately reflected in handoff.md",
+    "pass_criteria": "Returns valid=true and empty unrecorded_commits when handoff reflects git log",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-MEM-C03",
+    "category": "MEMORY",
+    "layer": "UNIT",
+    "description": "Preserves section 4 Intentos fallidos and flags any attempt to mutate or delete it",
+    "pass_criteria": "Throws or flags error if section 4 is deleted or corrupted in handoff",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CAPSULE-D01",
+    "category": "CAPSULE",
+    "layer": "UNIT",
+    "description": "Context capsule projection excludes ephemeral conversation logs and noise",
+    "pass_criteria": "Generates capsule without any chat history or transient prompt messages",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CAPSULE-D02",
+    "category": "CAPSULE",
+    "layer": "UNIT",
+    "description": "Validates capsule determinism and size budget compliance (< 32KB)",
+    "pass_criteria": "Capsule bytes <= 32768 and canonical hash is identical across successive runs",
+    "gate": "REQUIRED"
+  }
+]
+```

package/specs/014-gemstack-2.0-context-memory/tasks.md

@@ -0,0 +1,79 @@
+# Tasks Breakdown: Gemstack 2.0 Sprint D — Efficient Context & Persistent Memory
+
+**Feature ID:** `014-gemstack-2.0-context-memory`  
+**Phase:** `tasks`  
+**Parent Release:** `gemstack-ai@2.0.0-alpha`
+
+---
+
+## 1. Inherited Architecture Contracts
+
+```gemstack-contracts
+[
+  {
+    "id": "context-fatigue-guard",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  },
+  {
+    "id": "offline-dependency-audit",
+    "type": "ENUM_SET",
+    "values": [
+      "orphan-detector",
+      "undeclared-detector",
+      "circular-cycle-detector",
+      "offline-purity"
+    ]
+  },
+  {
+    "id": "memory-git-cross-audit",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  },
+  {
+    "id": "capsule-noise-elimination",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  }
+]
+```
+
+---
+
+## 2. Task Inventory
+
+- [x] **TASK-001: Author comprehensive test suite for Context & Memory**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-FATIGUE-A01, TEST-FATIGUE-A02, TEST-FATIGUE-A03, TEST-DEP-B01, TEST-DEP-B02, TEST-DEP-B03, TEST-DEP-B04, TEST-MEM-C01, TEST-MEM-C02, TEST-MEM-C03, TEST-CAPSULE-D01, TEST-CAPSULE-D02 -->
+  <!-- gemstack:files=tests/context-memory-p1.test.js -->
+  <!-- gemstack:depends= -->
+
+- [x] **TASK-002: Implement Context Fatigue Engine & Noise Pruning**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-FATIGUE-A01, TEST-FATIGUE-A02, TEST-FATIGUE-A03 -->
+  <!-- gemstack:files=src/lib/context-fatigue.js -->
+  <!-- gemstack:depends=TASK-001 -->
+
+- [x] **TASK-003: Implement Offline Dependency Auditor**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-DEP-B01, TEST-DEP-B02, TEST-DEP-B03, TEST-DEP-B04 -->
+  <!-- gemstack:files=src/lib/dependency-audit.js -->
+  <!-- gemstack:depends=TASK-001 -->
+
+- [x] **TASK-004: Implement Memory Cross-Auditor**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-MEM-C01, TEST-MEM-C02, TEST-MEM-C03 -->
+  <!-- gemstack:files=src/lib/memory-audit.js -->
+  <!-- gemstack:depends=TASK-001 -->
+
+- [x] **TASK-005: Enforce Capsule Noise Elimination and Determinism**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-CAPSULE-D01, TEST-CAPSULE-D02 -->
+  <!-- gemstack:files=src/lib/context-capsule.js -->
+  <!-- gemstack:depends=TASK-001 -->
+
+- [x] **TASK-006: Integrate CLI commands, wire test suite, and collect closure evidence**
+  <!-- gemstack:validation_required=true -->
+  <!-- gemstack:tests=TEST-FATIGUE-A01, TEST-FATIGUE-A02, TEST-FATIGUE-A03, TEST-DEP-B01, TEST-DEP-B02, TEST-DEP-B03, TEST-DEP-B04, TEST-MEM-C01, TEST-MEM-C02, TEST-MEM-C03, TEST-CAPSULE-D01, TEST-CAPSULE-D02 -->
+  <!-- gemstack:files=src/commands/doctor.js, src/commands/verify.js, package.json -->
+  <!-- gemstack:depends=TASK-002, TASK-003, TASK-004, TASK-005 -->

package/src/cli.js

@@ -14,6 +14,7 @@ const shipCommand = require('./commands/ship');
 const contextCommand = require('./commands/context');
 const swarmCommand = require('./commands/swarm');
 const visualCommand = require('./commands/visual');
+const specCommand = require('./commands/spec');
 
 async function main() {
     const { command, args, flags } = parser.parse(process.argv);
@@ -30,6 +31,7 @@ Commands:
   context   Generate, show, or verify context capsule
   swarm     Plan or validate agent swarm work and write partitions
   vqa       Validate or promote visual QA manifests and evidence
+  spec      Validate spec rigor, merge concurrent specs, and check conflicts
   list      List available skills
   show      Show content of a skill
   handoff   Show content of handoff.md
@@ -58,6 +60,7 @@ Options:
             case 'swarm': await swarmCommand(args, flags); break;
             case 'vqa':
             case 'visual': await visualCommand(args, flags); break;
+            case 'spec': await specCommand(args, flags); break;
             case 'list': await listCommand(flags); break;
             case 'show': await showCommand(args[0], flags); break;
             case 'hooks': hooksCommand.installHooks(flags.target); break;

package/src/commands/doctor.js

@@ -46,5 +46,23 @@ module.exports = async (flags) => {
     } else {
         logger.warn('.gitignore is not patched.');
     }
+
+    // Offline Dependency Audit (Gemstack 2.0 Sprint D)
+    const { auditDependencies } = require('../lib/dependency-audit');
+    const depAudit = auditDependencies(targetDir);
+    if (depAudit.orphans.length > 0) {
+        logger.warn(`Orphan dependencies detected in package.json: ${depAudit.orphans.join(', ')}`);
+    } else {
+        logger.ok('Zero orphan dependencies detected.');
+    }
+    if (depAudit.undeclared.length > 0) {
+        logger.warn(`Undeclared dependencies used in source: ${depAudit.undeclared.join(', ')}`);
+    }
+    if (depAudit.circularCycles.length > 0) {
+        logger.warn(`Circular import cycles detected: ${depAudit.circularCycles.map(c => c.join(' -> ')).join('; ')}`);
+    } else {
+        logger.ok('Zero circular import cycles detected.');
+    }
+
     logger.ok('Doctor checks completed.');
 };