sinapse-ai 9.4.0 → 9.5.0

package/.sinapse-ai/development/templates/service-template/package.json.hbs

@@ -1,88 +1,88 @@
-{
-  "name": "@sinapse/{{kebabCase serviceName}}",
-  "version": "1.0.0",
-  "description": "{{description}}",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./types": {
-      "types": "./dist/types.d.ts",
-      "import": "./dist/types.js"
-    },
-    "./errors": {
-      "types": "./dist/errors.d.ts",
-      "import": "./dist/errors.js"
-    }{{#if isApiIntegration}},
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
-    }{{/if}}
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "build:watch": "tsc --watch",
-    "clean": "rimraf dist coverage",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint . --ext .ts",
-    "lint:fix": "eslint . --ext .ts --fix",
-    "prepublishOnly": "npm run clean && npm run build && npm test"
-  },
-  "keywords": [
-    "sinapse",
-    "{{kebabCase serviceName}}",
-    "service"{{#if isApiIntegration}},
-    "api",
-    "integration"{{/if}}
-  ],
-  "author": "SINAPSE-FullStack",
-  "license": "MIT",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.12",
-    "@types/node": "^20.11.0",
-    "@typescript-eslint/eslint-plugin": "^6.19.0",
-    "@typescript-eslint/parser": "^6.19.0",
-    "eslint": "^8.56.0",
-    "jest": "^29.7.0",
-    "rimraf": "^5.0.5",
-    "ts-jest": "^29.1.2",
-    "typescript": "^5.3.3"
-  },
-  "peerDependencies": {
-    "typescript": ">=5.0.0"
-  },
-  "peerDependenciesMeta": {
-    "typescript": {
-      "optional": true
-    }
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/sinapse-fullstack/{{kebabCase serviceName}}.git"
-  },
-  "bugs": {
-    "url": "https://github.com/sinapse-fullstack/{{kebabCase serviceName}}/issues"
-  },
-  "homepage": "https://github.com/sinapse-fullstack/{{kebabCase serviceName}}#readme",
-  "sinapse": {
-    "storyId": "{{storyId}}",
-    "type": "{{#if isApiIntegration}}api-integration{{else}}utility-service{{/if}}",
-    "generatedAt": "{{generatedAt}}"
-  }
-}
-
+{
+  "name": "@sinapse/{{kebabCase serviceName}}",
+  "version": "1.0.0",
+  "description": "{{description}}",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    }{{#if isApiIntegration}},
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }{{/if}}
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rimraf dist coverage",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "sinapse",
+    "{{kebabCase serviceName}}",
+    "service"{{#if isApiIntegration}},
+    "api",
+    "integration"{{/if}}
+  ],
+  "author": "SINAPSE-FullStack",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sinapse-fullstack/{{kebabCase serviceName}}.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sinapse-fullstack/{{kebabCase serviceName}}/issues"
+  },
+  "homepage": "https://github.com/sinapse-fullstack/{{kebabCase serviceName}}#readme",
+  "sinapse": {
+    "storyId": "{{storyId}}",
+    "type": "{{#if isApiIntegration}}api-integration{{else}}utility-service{{/if}}",
+    "generatedAt": "{{generatedAt}}"
+  }
+}
+

package/.sinapse-ai/development/templates/service-template/types.ts.hbs

@@ -1,146 +1,146 @@
-/**
- * Type definitions for {{pascalCase serviceName}} service.
- * @module @sinapse/{{kebabCase serviceName}}/types
- * @story {{storyId}}
- */
-
-/**
- * Configuration options for the {{pascalCase serviceName}} service.
- */
-export interface {{pascalCase serviceName}}Config {
-{{#each envVars}}
-  /**
-   * {{this.description}}
-   {{#if this.required}}
-   * @required
-   {{/if}}
-   */
-  {{camelCase this.name}}{{#unless this.required}}?{{/unless}}: string;
-
-{{/each}}
-{{#if isApiIntegration}}
-  /**
-   * Base URL for the API.
-   * @default '{{apiBaseUrl}}'
-   */
-  baseUrl?: string;
-
-  /**
-   * Request timeout in milliseconds.
-   * @default 30000
-   */
-  timeout?: number;
-
-  /**
-   * Maximum number of retry attempts.
-   * @default 3
-   */
-  maxRetries?: number;
-
-  /**
-   * Enable debug logging.
-   * @default false
-   */
-  debug?: boolean;
-
-{{/if}}
-}
-
-/**
- * The {{pascalCase serviceName}} service interface.
- */
-export interface {{pascalCase serviceName}}Service {
-  /**
-   * Execute the primary service operation.
-   */
-  execute(): Promise<void>;
-
-  /**
-   * Get the current configuration (without sensitive values).
-   */
-  getConfig(): Partial<{{pascalCase serviceName}}Config>;
-
-  /**
-   * Check if the service is properly configured and operational.
-   */
-  healthCheck(): Promise<boolean>;
-}
-
-{{#if isApiIntegration}}
-/**
- * Base API response structure.
- */
-export interface {{pascalCase serviceName}}ApiResponse<T = unknown> {
-  success: boolean;
-  data?: T;
-  error?: {
-    code: string;
-    message: string;
-    details?: Record<string, unknown>;
-  };
-  meta?: {
-    requestId?: string;
-    rateLimit?: {
-      remaining: number;
-      reset: number;
-    };
-  };
-}
-
-/**
- * Request options for API calls.
- */
-export interface {{pascalCase serviceName}}RequestOptions {
-  /**
-   * HTTP method.
-   */
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-
-  /**
-   * Request headers.
-   */
-  headers?: Record<string, string>;
-
-  /**
-   * Request body.
-   */
-  body?: unknown;
-
-  /**
-   * Query parameters.
-   */
-  params?: Record<string, string | number | boolean>;
-
-  /**
-   * Request timeout override.
-   */
-  timeout?: number;
-
-  /**
-   * Skip retry on failure.
-   */
-  noRetry?: boolean;
-}
-
-/**
- * Rate limit information.
- */
-export interface {{pascalCase serviceName}}RateLimit {
-  /**
-   * Maximum requests allowed.
-   */
-  limit: number;
-
-  /**
-   * Remaining requests in current window.
-   */
-  remaining: number;
-
-  /**
-   * Unix timestamp when the rate limit resets.
-   */
-  reset: number;
-}
-
-{{/if}}
-
+/**
+ * Type definitions for {{pascalCase serviceName}} service.
+ * @module @sinapse/{{kebabCase serviceName}}/types
+ * @story {{storyId}}
+ */
+
+/**
+ * Configuration options for the {{pascalCase serviceName}} service.
+ */
+export interface {{pascalCase serviceName}}Config {
+{{#each envVars}}
+  /**
+   * {{this.description}}
+   {{#if this.required}}
+   * @required
+   {{/if}}
+   */
+  {{camelCase this.name}}{{#unless this.required}}?{{/unless}}: string;
+
+{{/each}}
+{{#if isApiIntegration}}
+  /**
+   * Base URL for the API.
+   * @default '{{apiBaseUrl}}'
+   */
+  baseUrl?: string;
+
+  /**
+   * Request timeout in milliseconds.
+   * @default 30000
+   */
+  timeout?: number;
+
+  /**
+   * Maximum number of retry attempts.
+   * @default 3
+   */
+  maxRetries?: number;
+
+  /**
+   * Enable debug logging.
+   * @default false
+   */
+  debug?: boolean;
+
+{{/if}}
+}
+
+/**
+ * The {{pascalCase serviceName}} service interface.
+ */
+export interface {{pascalCase serviceName}}Service {
+  /**
+   * Execute the primary service operation.
+   */
+  execute(): Promise<void>;
+
+  /**
+   * Get the current configuration (without sensitive values).
+   */
+  getConfig(): Partial<{{pascalCase serviceName}}Config>;
+
+  /**
+   * Check if the service is properly configured and operational.
+   */
+  healthCheck(): Promise<boolean>;
+}
+
+{{#if isApiIntegration}}
+/**
+ * Base API response structure.
+ */
+export interface {{pascalCase serviceName}}ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+  meta?: {
+    requestId?: string;
+    rateLimit?: {
+      remaining: number;
+      reset: number;
+    };
+  };
+}
+
+/**
+ * Request options for API calls.
+ */
+export interface {{pascalCase serviceName}}RequestOptions {
+  /**
+   * HTTP method.
+   */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+  /**
+   * Request headers.
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Request body.
+   */
+  body?: unknown;
+
+  /**
+   * Query parameters.
+   */
+  params?: Record<string, string | number | boolean>;
+
+  /**
+   * Request timeout override.
+   */
+  timeout?: number;
+
+  /**
+   * Skip retry on failure.
+   */
+  noRetry?: boolean;
+}
+
+/**
+ * Rate limit information.
+ */
+export interface {{pascalCase serviceName}}RateLimit {
+  /**
+   * Maximum requests allowed.
+   */
+  limit: number;
+
+  /**
+   * Remaining requests in current window.
+   */
+  remaining: number;
+
+  /**
+   * Unix timestamp when the rate limit resets.
+   */
+  reset: number;
+}
+
+{{/if}}
+

package/.sinapse-ai/development/templates/squad-template/LICENSE

@@ -1,22 +1,22 @@
-MIT License
-
-Copyright (c) {{year}} {{author}}
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
+MIT License
+
+Copyright (c) {{year}} {{author}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/.sinapse-ai/development/workflows/story-development-cycle.yaml

@@ -272,14 +272,53 @@ workflow:
 
       Retornando para Dev corrigir...
 
+  # ──────────────────────────────────────────────────────────────────────────
+  # Agent Handoff Compaction — wired v1.1 (fw-v2.6, EPIC-framework-upgrade-v2)
+  # ──────────────────────────────────────────────────────────────────────────
+  # Operational enforcement of the handoff compaction protocol. The outgoing
+  # agent of each phase MUST run `generate-agent-handoff` task before the
+  # incoming agent is activated. This collapses persona context from ~3-5K
+  # tokens to ~379 per switch (90%+ compaction).
+  #
+  # Reference:
+  #   - Task: .sinapse-ai/development/tasks/generate-agent-handoff.md
+  #   - Rule: .claude/rules/agent-handoff.md
+  #   - Template: .sinapse-ai/development/templates/agent-handoff-tmpl.yaml
+  handoff_hooks:
+    enabled: true
+    task: generate-agent-handoff
+    transitions:
+      - from: create        # sprint-lead (sm)
+        to: validate        # product-lead (po)
+        required: true
+      - from: validate      # product-lead (po)
+        to: implement       # developer (dev)
+        required: true
+      - from: implement     # developer (dev)
+        to: review          # quality-gate (qa)
+        required: true
+    storage: ".sinapse/handoffs/"
+    max_tokens_per_artifact: 500
+    on_failure: "warn-and-proceed"  # per graceful-degradation principle in ids-principles.md
+
 metadata:
   author: Orion (SINAPSE Master)
   created_date: 2025-01-30
-  version: 1.0.0
+  version: 1.1.0
+  version_history:
+    - version: 1.0.0
+      date: 2025-01-30
+      author: Orion
+      notes: "Initial 4-phase SDC workflow"
+    - version: 1.1.0
+      date: 2026-04-12
+      author: "Imperator (sinapse-orqx) via fw-v2.6"
+      notes: "Wired handoff_hooks to enforce agent handoff compaction between phase transitions. No breaking changes — existing sequence untouched."
   tags:
     - story
     - development-cycle
     - quality-gate
     - agile
     - generic
+    - handoff-compaction
 

package/.sinapse-ai/hooks/ids-post-commit.js

@@ -111,6 +111,28 @@ async function main() {
     // Post-commit hook should NEVER block workflow
     console.error(`[IDS-Hook] Registry update failed (non-blocking): ${err.message}`);
   }
+
+  // Story 10.27 — When .sinapse-ai/ files changed, the registry update we
+  // just ran (and any other auto-managed file under .sinapse-ai/) needs the
+  // install-manifest.yaml to be refreshed too, otherwise the next commit's
+  // pre-commit hook will print "manifest outdated". Regenerate it here so
+  // the working tree converges to a clean state after every commit.
+  const sinapseChanges = changes.some(
+    (c) => c.relativePath && c.relativePath.startsWith('.sinapse-ai/'),
+  );
+  if (sinapseChanges) {
+    try {
+      const { generateManifest, writeManifest } = require(
+        path.resolve(REPO_ROOT, 'scripts/generate-install-manifest.js'),
+      );
+      const manifest = await generateManifest();
+      await writeManifest(manifest);
+      console.log('[IDS-Hook] install-manifest.yaml regenerated to stay in sync.');
+    } catch (err) {
+      // Same non-blocking philosophy as the registry update
+      console.error(`[IDS-Hook] Manifest regen failed (non-blocking): ${err.message}`);
+    }
+  }
 }
 
 main();

package/.sinapse-ai/infrastructure/contracts/compatibility/README.md

@@ -0,0 +1,42 @@
+# Compatibility Contracts
+
+This directory stores the cross-IDE compatibility contracts read by
+`.sinapse-ai/infrastructure/scripts/validate-parity.js`.
+
+## Files
+
+| File | Purpose | When to edit |
+|------|---------|--------------|
+| `sinapse-current.yaml` | Authoritative contract for the current release | Whenever the IDE matrix, required-checks, or expected statuses change |
+| `sinapse-4.0.4.yaml` | Historical snapshot of the 4.0.4-era contract | Never (kept as a frozen reference for diffing) |
+
+## Resolution Policy
+
+The validator's `getDefaultContractPath()` always prefers `sinapse-current.yaml`
+when it exists on disk. The legacy `sinapse-4.0.4.yaml` is read only as a
+fallback for repositories that have not yet been migrated.
+
+Story 10.18 introduced this split because pinning the validator to a single
+versioned filename caused the contract to silently track a stale release for
+five major versions (4.0.4 → 9.4.0 → v10.0.0 target).
+
+## Updating the Contract
+
+1. Edit `sinapse-current.yaml` in place.
+2. Bump the `release` field to the new SINAPSE version label (e.g. `SINAPSE 10.1.0`).
+3. Bump `updated_at` to today's date (ISO format).
+4. Run `npm run validate:parity` to verify the new contract still passes.
+5. If the change adds or removes a required check, run `npm test` to make
+   sure no parity unit test is hard-coded to the old shape.
+
+## Diffing Two Contracts
+
+Use the validator's `--diff` flag to compare the current contract against
+any historical snapshot:
+
+```bash
+npm run validate:parity -- --diff=.sinapse-ai/infrastructure/contracts/compatibility/sinapse-4.0.4.yaml
+```
+
+The diff output is shown both in the human-readable report and in `--json`
+mode under `contractDiff`.

package/.sinapse-ai/infrastructure/contracts/compatibility/sinapse-current.yaml

@@ -0,0 +1,35 @@
+# Compatibility Contract — current
+#
+# This file is the authoritative compatibility contract for the CURRENT release.
+# When the IDE matrix or required-checks set changes, edit this file in place
+# and bump the release/updated_at fields.
+#
+# A snapshot of the previous contract may be kept under a versioned name
+# (e.g. sinapse-4.0.4.yaml) to support contract diffing via the validator's
+# --diff=<path> flag, but the loader always prefers sinapse-current.yaml.
+#
+# See README.md in this directory for the versioning policy.
+
+release: "SINAPSE 10.0.0"
+updated_at: "2026-04-12"
+source_of_truth:
+  docs_matrix: "docs/ide-integration.md"
+  validator: ".sinapse-ai/infrastructure/scripts/validate-parity.js"
+
+global_required_checks:
+  - paths
+
+ide_matrix:
+  - ide: "claude-code"
+    display_name: "Claude Code"
+    expected_status: "Works"
+    required_checks:
+      - claude-sync
+      - claude-integration
+  - ide: "codex"
+    display_name: "Codex CLI"
+    expected_status: "Limited"
+    required_checks:
+      - codex-sync
+      - codex-integration
+      - codex-skills