@sniper.ai/core 2.0.0 → 3.1.0

package/schemas/checkpoint.schema.yaml

@@ -0,0 +1,133 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/checkpoint"
+title: Phase Checkpoint
+description: Schema for SNIPER phase checkpoint files that track progress through lifecycle phases.
+type: object
+required:
+  - protocol
+  - phase
+  - timestamp
+  - status
+properties:
+  protocol:
+    type: string
+    description: The SNIPER protocol version identifier.
+  phase:
+    type: string
+    description: The lifecycle phase this checkpoint belongs to (e.g. discover, plan, implement, review).
+  timestamp:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when this checkpoint was recorded.
+  status:
+    type: string
+    enum:
+      - in_progress
+      - completed
+      - failed
+    description: Current status of the phase.
+  agents:
+    type: array
+    description: List of agents participating in this phase.
+    items:
+      type: object
+      required:
+        - name
+        - status
+        - tasks_completed
+        - tasks_total
+      properties:
+        name:
+          type: string
+          description: Agent persona name.
+        status:
+          type: string
+          enum:
+            - active
+            - completed
+            - failed
+          description: Current status of the agent.
+        tasks_completed:
+          type: integer
+          minimum: 0
+          description: Number of tasks the agent has completed.
+        tasks_total:
+          type: integer
+          minimum: 0
+          description: Total number of tasks assigned to the agent.
+  gate_result:
+    oneOf:
+      - type: "null"
+      - type: object
+        required:
+          - result
+          - blocking_failures
+        properties:
+          result:
+            type: string
+            enum:
+              - pass
+              - fail
+            description: Overall gate review result.
+          blocking_failures:
+            type: integer
+            minimum: 0
+            description: Number of blocking check failures.
+    description: Gate review result, or null if the gate has not been run yet.
+  artifacts_produced:
+    type: array
+    description: List of artifacts produced during this phase.
+    items:
+      type: object
+      required:
+        - path
+        - status
+      properties:
+        path:
+          type: string
+          description: File path of the produced artifact.
+        status:
+          type: string
+          enum:
+            - draft
+            - complete
+          description: Whether the artifact is a draft or complete.
+  token_usage:
+    type: object
+    description: Token consumption metrics for this phase.
+    properties:
+      phase_tokens:
+        type: integer
+        minimum: 0
+        description: Tokens consumed during this phase.
+      cumulative_tokens:
+        type: integer
+        minimum: 0
+        description: Total tokens consumed across all phases up to and including this one.
+      budget_remaining:
+        type: number
+        minimum: 0
+        description: Remaining token budget.
+  commits:
+    type: array
+    description: Git commits made during this phase, used for logical revert.
+    items:
+      type: object
+      required:
+        - sha
+        - message
+        - agent
+      properties:
+        sha:
+          type: string
+          description: Git commit SHA.
+        message:
+          type: string
+          description: Commit message.
+        agent:
+          type: string
+          description: Agent that produced this commit.
+  notes:
+    type: string
+    description: Free-form notes about the checkpoint.
+additionalProperties: false

package/schemas/cost.schema.yaml

@@ -0,0 +1,97 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/cost"
+title: Cost Tracking
+description: Schema for SNIPER cost tracking that monitors token usage and budget across phases.
+type: object
+required:
+  - protocol
+  - started_at
+  - budget
+properties:
+  protocol:
+    type: string
+    description: The SNIPER protocol version identifier.
+  started_at:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when cost tracking began.
+  budget:
+    type: number
+    minimum: 0
+    description: Total token budget allocated for the project.
+  phases:
+    type: array
+    description: Per-phase cost breakdown.
+    items:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: Phase name (e.g. discover, plan, implement, review).
+        started_at:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when this phase started.
+        completed_at:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when this phase completed.
+        tokens_used:
+          type: integer
+          minimum: 0
+          description: Total tokens consumed during this phase.
+        agents:
+          type: array
+          description: Per-agent cost breakdown within this phase.
+          items:
+            type: object
+            required:
+              - name
+              - tokens_used
+            properties:
+              name:
+                type: string
+                description: Agent persona name.
+              tokens_used:
+                type: integer
+                minimum: 0
+                description: Tokens consumed by this agent.
+  totals:
+    type: object
+    description: Aggregate cost totals.
+    properties:
+      tokens_used:
+        type: integer
+        minimum: 0
+        description: Total tokens consumed across all phases.
+      budget_remaining:
+        type: number
+        minimum: 0
+        description: Remaining token budget.
+      budget_percent_used:
+        type: number
+        minimum: 0
+        maximum: 100
+        description: Percentage of budget consumed.
+  enforcement:
+    type: object
+    description: Budget enforcement thresholds expressed as fractions of the total budget.
+    properties:
+      warn_threshold:
+        type: number
+        minimum: 0
+        maximum: 1
+        description: Fraction of budget at which a warning is issued.
+      soft_cap:
+        type: number
+        minimum: 0
+        maximum: 1
+        description: Fraction of budget at which soft enforcement begins (e.g. require confirmation).
+      hard_cap:
+        type: number
+        minimum: 0
+        maximum: 1
+        description: Fraction of budget at which execution is halted.
+additionalProperties: false

package/schemas/dependency-graph.schema.yaml

@@ -0,0 +1,37 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/dependency-graph"
+title: Cross-Project Dependency Graph
+description: Schema for tracking API dependencies between projects in a SNIPER workspace.
+type: object
+required:
+  - projects
+properties:
+  projects:
+    type: array
+    items:
+      type: object
+      required: [name, exports, imports]
+      properties:
+        name:
+          type: string
+        exports:
+          type: array
+          items:
+            type: object
+            required: [api, file]
+            properties:
+              api: { type: string, description: "API endpoint or export name" }
+              file: { type: string, description: "Source file path" }
+              version: { type: string }
+        imports:
+          type: array
+          items:
+            type: object
+            required: [api, from_project]
+            properties:
+              api: { type: string }
+              from_project: { type: string }
+  updated_at:
+    type: string
+    format: date-time
+additionalProperties: false

package/schemas/gate-result.schema.yaml

@@ -0,0 +1,101 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/gate-result"
+title: Gate Result
+description: Schema for SNIPER gate review results that determine whether a phase passes its quality gate.
+type: object
+required:
+  - gate
+  - timestamp
+  - result
+  - blocking_failures
+  - total_checks
+properties:
+  gate:
+    type: string
+    description: The phase name this gate review applies to.
+  timestamp:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the gate review was performed.
+  result:
+    type: string
+    enum:
+      - pass
+      - fail
+    description: Overall gate review result.
+  checks:
+    type: array
+    description: Individual check results that make up the gate review.
+    items:
+      type: object
+      required:
+        - id
+        - status
+        - blocking
+        - output
+      properties:
+        id:
+          type: string
+          description: Unique identifier for this check.
+        status:
+          type: string
+          enum:
+            - pass
+            - fail
+          description: Whether this individual check passed or failed.
+        blocking:
+          type: boolean
+          description: Whether this check is a blocking check (failure prevents gate pass).
+        output:
+          type: string
+          description: Descriptive output or message from the check.
+  blocking_failures:
+    type: integer
+    minimum: 0
+    description: Number of blocking checks that failed.
+  total_checks:
+    type: integer
+    minimum: 0
+    description: Total number of checks that were evaluated.
+  model_results:
+    type: array
+    description: Individual model assessments when multi-model review is enabled.
+    items:
+      type: object
+      required:
+        - model
+        - result
+        - timestamp
+      properties:
+        model:
+          type: string
+          description: Model identifier used for this assessment.
+        result:
+          type: string
+          enum:
+            - pass
+            - fail
+          description: This model's gate result.
+        checks:
+          type: array
+          description: Check results from this model's assessment.
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+              status:
+                type: string
+                enum:
+                  - pass
+                  - fail
+              output:
+                type: string
+        timestamp:
+          type: string
+          format: date-time
+          description: When this model's assessment was performed.
+  consensus:
+    type: boolean
+    description: Whether all models agreed on the result. Only present when multi-model review is enabled.
+additionalProperties: false

package/schemas/knowledge-manifest.schema.yaml

@@ -0,0 +1,39 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/knowledge-manifest"
+title: Knowledge Manifest
+description: Schema for SNIPER knowledge manifest files that declare domain knowledge sources available to agents.
+type: object
+required:
+  - sources
+properties:
+  sources:
+    type: array
+    description: List of domain knowledge sources available for agent injection.
+    minItems: 1
+    items:
+      type: object
+      required:
+        - topic
+        - file
+        - tokens
+      properties:
+        topic:
+          type: string
+          description: Short identifier for the knowledge domain (e.g. telephony, compliance, crm).
+        file:
+          type: string
+          description: Path to the knowledge file, relative to .sniper/knowledge/.
+        tokens:
+          type: integer
+          minimum: 1
+          description: Estimated token count of the knowledge file, used for budget planning.
+        tags:
+          type: array
+          description: Searchable tags for matching knowledge to agent context.
+          items:
+            type: string
+        description:
+          type: string
+          description: Human-readable summary of what this knowledge source covers.
+      additionalProperties: false
+additionalProperties: false

package/schemas/live-status.schema.yaml

@@ -0,0 +1,122 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/live-status"
+title: Live Status
+description: Schema for SNIPER real-time progress tracking across the project lifecycle.
+type: object
+required:
+  - protocol
+  - status
+properties:
+  protocol:
+    type: string
+    description: The SNIPER protocol version identifier.
+  status:
+    type: string
+    enum:
+      - idle
+      - running
+      - paused
+      - completed
+      - failed
+    description: Overall lifecycle execution status.
+  current_phase:
+    type: string
+    description: The phase currently being executed.
+  started_at:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the lifecycle run started.
+  updated_at:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of the most recent status update.
+  phases:
+    type: array
+    description: Per-phase status and progress.
+    items:
+      type: object
+      required:
+        - name
+        - status
+        - progress
+      properties:
+        name:
+          type: string
+          description: Phase name.
+        status:
+          type: string
+          enum:
+            - pending
+            - running
+            - paused
+            - completed
+            - failed
+          description: Current status of this phase.
+        agents:
+          type: array
+          description: Agents active in this phase.
+          items:
+            type: object
+            required:
+              - name
+              - status
+            properties:
+              name:
+                type: string
+                description: Agent persona name.
+              status:
+                type: string
+                enum:
+                  - active
+                  - completed
+                  - failed
+                description: Current status of the agent.
+        progress:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: Phase completion percentage.
+  gate_results:
+    type: array
+    description: Results from completed gate reviews.
+    items:
+      type: object
+      required:
+        - phase
+        - result
+        - timestamp
+      properties:
+        phase:
+          type: string
+          description: Phase that was reviewed.
+        result:
+          type: string
+          enum:
+            - pass
+            - fail
+          description: Gate review outcome.
+        timestamp:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when the gate review completed.
+  cost:
+    type: object
+    description: Current cost snapshot.
+    properties:
+      tokens_used:
+        type: integer
+        minimum: 0
+        description: Total tokens consumed so far.
+      budget:
+        type: number
+        minimum: 0
+        description: Total token budget.
+      percent:
+        type: number
+        minimum: 0
+        maximum: 100
+        description: Percentage of budget consumed.
+  next_action:
+    type: string
+    description: Description of the next expected action or step.
+additionalProperties: false

package/schemas/protocol-meta.schema.yaml

@@ -0,0 +1,58 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/protocol-meta"
+title: ProtocolMeta
+description: Metadata for a protocol run, stored at .sniper/artifacts/{protocol_id}/meta.yaml.
+type: object
+required:
+  - id
+  - protocol
+  - status
+  - started
+properties:
+  id:
+    type: string
+    pattern: "^SNPR-\\d{8}-[a-f0-9]{4}$"
+    description: Timestamp-based protocol ID (e.g., SNPR-20260307-a3f2).
+  protocol:
+    type: string
+    description: Protocol name (full, feature, patch, etc.).
+  description:
+    type: string
+    description: Human-readable description of what this protocol run does.
+  status:
+    type: string
+    enum: [in_progress, completed, failed, cancelled]
+    description: Current status of the protocol run.
+  started:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the protocol started.
+  completed:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the protocol completed.
+  agents:
+    type: array
+    items:
+      type: string
+    description: List of agent names used in this run.
+  token_usage:
+    type: integer
+    minimum: 0
+    description: Total tokens consumed during this run.
+  gate_results:
+    type: object
+    additionalProperties:
+      type: string
+      enum: [pass, fail]
+    description: Gate results per phase.
+  stories_count:
+    type: integer
+    minimum: 0
+    description: Number of stories created.
+  commits:
+    type: array
+    items:
+      type: string
+    description: Git commit SHAs produced during this run.
+additionalProperties: true

package/schemas/protocol.schema.yaml

@@ -0,0 +1,100 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/protocol"
+title: SNIPER Protocol
+description: Schema for SNIPER protocol definition files that define lifecycle phase sequences.
+type: object
+required:
+  - name
+  - description
+  - budget
+  - phases
+properties:
+  name:
+    type: string
+    description: Unique protocol identifier (e.g. full, feature, patch, hotfix).
+  description:
+    type: string
+    description: Human-readable description of the protocol's purpose.
+  budget:
+    type: integer
+    minimum: 1
+    description: Maximum token budget for the entire protocol execution.
+  phases:
+    type: array
+    minItems: 1
+    description: Ordered list of phases that compose this protocol.
+    items:
+      type: object
+      required:
+        - name
+        - description
+        - agents
+        - spawn_strategy
+      properties:
+        name:
+          type: string
+          description: Phase identifier (e.g. discover, plan, implement, review).
+        description:
+          type: string
+          description: Human-readable description of what this phase accomplishes.
+        agents:
+          type: array
+          minItems: 1
+          items:
+            type: string
+          description: Agent personas assigned to this phase.
+        spawn_strategy:
+          type: string
+          enum:
+            - single
+            - team
+          description: Whether to spawn a single agent or a coordinated team.
+        gate:
+          type: object
+          properties:
+            checklist:
+              type: string
+              description: Name of the checklist to evaluate at the gate.
+            human_approval:
+              type: boolean
+              description: Whether a human must approve the gate before proceeding.
+            multi_model_checklist:
+              type: string
+              description: Checklist to use for multi-model review (optional).
+          required:
+            - checklist
+            - human_approval
+          additionalProperties: false
+          description: Quality gate configuration for this phase.
+        outputs:
+          type: array
+          items:
+            type: string
+          description: Expected artifacts produced by this phase.
+        plan_approval:
+          type: boolean
+          description: Whether agents must get their plan approved before executing.
+        coordination:
+          type: array
+          description: Inter-agent coordination constraints for team phases.
+          items:
+            type: object
+            required:
+              - between
+              - topic
+            properties:
+              between:
+                type: array
+                minItems: 2
+                items:
+                  type: string
+                description: Agent personas that must coordinate.
+              topic:
+                type: string
+                description: Description of the coordination requirement.
+            additionalProperties: false
+      additionalProperties: false
+  auto_retro:
+    type: boolean
+    description: Whether to trigger the retro-analyst after protocol completion.
+additionalProperties: false