@sniper.ai/core 2.0.0 → 3.0.0

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.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

package/schemas/retro.schema.yaml

@@ -0,0 +1,95 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/retro"
+title: Retrospective Report
+description: Schema for SNIPER retrospective reports generated after a lifecycle run completes.
+type: object
+required:
+  - protocol
+  - completed_at
+properties:
+  protocol:
+    type: string
+    description: The SNIPER protocol version identifier.
+  completed_at:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the lifecycle run completed.
+  duration_phases:
+    type: array
+    description: Per-phase duration and execution summary.
+    items:
+      type: object
+      required:
+        - phase
+        - agents
+        - gate_attempts
+        - gate_result
+      properties:
+        phase:
+          type: string
+          description: Phase name.
+        agents:
+          type: integer
+          minimum: 0
+          description: Number of agents that participated in this phase.
+        gate_attempts:
+          type: integer
+          minimum: 0
+          description: Number of times the gate review was attempted.
+        gate_result:
+          type: string
+          enum:
+            - pass
+            - fail
+          description: Final gate review outcome for this phase.
+  metrics:
+    type: object
+    description: Aggregate metrics for the entire lifecycle run.
+    properties:
+      total_tokens:
+        type: integer
+        minimum: 0
+        description: Total tokens consumed across all phases.
+      total_agents_spawned:
+        type: integer
+        minimum: 0
+        description: Total number of agents spawned across all phases.
+      gate_pass_rate:
+        type: number
+        minimum: 0
+        maximum: 1
+        description: Fraction of gate reviews that passed on the first attempt.
+  findings:
+    type: object
+    description: Retrospective findings and action items.
+    properties:
+      went_well:
+        type: array
+        description: Things that went well during the lifecycle run.
+        items:
+          type: string
+      needs_improvement:
+        type: array
+        description: Areas that need improvement.
+        items:
+          type: string
+      action_items:
+        type: array
+        description: Concrete action items for future runs.
+        items:
+          type: string
+  velocity:
+    type: object
+    description: Velocity metrics for this execution, used for budget calibration.
+    properties:
+      wall_clock_seconds:
+        type: number
+        minimum: 0
+        description: Total wall clock time for the protocol execution in seconds.
+      tokens_per_phase:
+        type: object
+        description: Token usage broken down by phase name.
+        additionalProperties:
+          type: integer
+          minimum: 0
+additionalProperties: false

package/schemas/revert-plan.schema.yaml

@@ -0,0 +1,40 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/revert-plan"
+title: Revert Plan
+description: Schema for SNIPER logical revert plans that track which commits to revert.
+type: object
+required:
+  - protocol
+  - commits_to_revert
+  - backup_branch
+  - target_state
+properties:
+  protocol:
+    type: string
+    description: Protocol ID being reverted.
+  phase:
+    type: string
+    description: Optional specific phase being reverted.
+  commits_to_revert:
+    type: array
+    items:
+      type: object
+      required: [sha, message, agent]
+      properties:
+        sha: { type: string }
+        message: { type: string }
+        agent: { type: string }
+    description: Commits to revert in reverse chronological order.
+  backup_branch:
+    type: string
+    description: Branch name for backup before revert.
+  target_state:
+    type: string
+    description: Description of the target state after revert.
+  created_at:
+    type: string
+    format: date-time
+  dry_run:
+    type: boolean
+    description: Whether this was a dry run only.
+additionalProperties: false

package/schemas/signal.schema.yaml

@@ -0,0 +1,39 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/signal"
+title: External Signal Record
+description: Schema for SNIPER signal records that capture learnings from CI failures, PR reviews, and production errors.
+type: object
+required:
+  - type
+  - source
+  - timestamp
+  - summary
+properties:
+  type:
+    type: string
+    enum: [ci_failure, pr_review_comment, production_error, manual]
+    description: Signal type classification.
+  source:
+    type: string
+    description: Where the signal came from (e.g., "github-actions", "pr-42", "datadog").
+  timestamp:
+    type: string
+    format: date-time
+  summary:
+    type: string
+    description: One-line summary of the signal.
+  details:
+    type: string
+    description: Full details (error message, review comment text, etc.).
+  learning:
+    type: string
+    description: Extracted learning or pattern to apply in future.
+  relevance_tags:
+    type: array
+    items: { type: string }
+    description: Tags for matching against agent context.
+  affected_files:
+    type: array
+    items: { type: string }
+    description: File paths affected by this signal.
+additionalProperties: false

package/schemas/velocity.schema.yaml

@@ -0,0 +1,52 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/velocity"
+title: Velocity
+description: Protocol execution history and calibrated budgets for adaptive budget selection.
+type: object
+required:
+  - executions
+properties:
+  executions:
+    type: array
+    description: History of protocol executions with timing and token data.
+    items:
+      type: object
+      required:
+        - protocol
+        - completed_at
+        - tokens_used
+      properties:
+        protocol:
+          type: string
+          description: Protocol name that was executed.
+        completed_at:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when the execution completed.
+        wall_clock_seconds:
+          type: number
+          minimum: 0
+          description: Wall clock duration of the execution in seconds.
+        tokens_used:
+          type: integer
+          minimum: 0
+          description: Total tokens consumed during the execution.
+        tokens_per_phase:
+          type: object
+          description: Token usage broken down by phase name.
+          additionalProperties:
+            type: integer
+            minimum: 0
+  calibrated_budgets:
+    type: object
+    description: p75 of token usage from last 5+ executions, keyed by protocol name.
+    additionalProperties:
+      type: integer
+      minimum: 0
+  rolling_averages:
+    type: object
+    description: Exponential moving average of token usage, keyed by protocol name.
+    additionalProperties:
+      type: number
+      minimum: 0
+additionalProperties: false

package/schemas/workspace-lock.schema.yaml

@@ -0,0 +1,34 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/workspace-lock"
+title: Workspace File Lock
+description: Schema for advisory file locks in SNIPER workspace coordination.
+type: object
+required:
+  - file
+  - locked_by
+  - since
+properties:
+  file:
+    type: string
+    description: Relative file path being locked.
+  locked_by:
+    type: object
+    required: [project, agent, protocol]
+    properties:
+      project:
+        type: string
+        description: Project name that holds the lock.
+      agent:
+        type: string
+        description: Agent that acquired the lock.
+      protocol:
+        type: string
+        description: Protocol execution that holds the lock.
+  since:
+    type: string
+    format: date-time
+    description: When the lock was acquired.
+  reason:
+    type: string
+    description: Why the lock was acquired.
+additionalProperties: false