@brawnen/agent-harness-protocol 0.1.0

package/schemas/report.schema.json

@@ -0,0 +1,245 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schemas/report.schema.json",
+  "title": "Harness Task Report",
+  "description": "任务完成后的结构化报告对象。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "task_id",
+    "intent",
+    "conclusion",
+    "actual_scope",
+    "evidence_summary",
+    "remaining_risks",
+    "next_steps",
+    "completed_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "0.3"
+    },
+    "task_id": {
+      "type": "string"
+    },
+    "intent": {
+      "type": "string"
+    },
+    "conclusion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "任务结论：根因判断（bug）、交付内容（feature）、调研结论（explore）"
+    },
+    "actual_scope": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "实际改动或分析范围，与合同 scope 对比"
+    },
+    "scope_deviation": {
+      "type": ["string", "null"],
+      "description": "与原始 scope 的偏差说明，无偏差时为 null"
+    },
+    "evidence_summary": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "type",
+          "result"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "command_result",
+              "test_result",
+              "diff_summary",
+              "artifact",
+              "reasoning_note",
+              "manual_confirmation"
+            ]
+          },
+          "result": {
+            "type": "string"
+          },
+          "passed": {
+            "type": "boolean"
+          }
+        }
+      }
+    },
+    "remaining_risks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "剩余风险，无则为空数组"
+    },
+    "overrides_used": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "本次任务中使用的 force_override 摘要"
+    },
+    "output_artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "changelog": {
+          "$ref": "#/$defs/output_artifact"
+        },
+        "design_note": {
+          "$ref": "#/$defs/output_artifact"
+        },
+        "adr": {
+          "$ref": "#/$defs/output_artifact"
+        }
+      }
+    },
+    "delivery_readiness": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "signals": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/delivery_signal"
+          }
+        },
+        "commit": {
+          "$ref": "#/$defs/delivery_readiness"
+        },
+        "push": {
+          "$ref": "#/$defs/delivery_readiness"
+        }
+      }
+    },
+    "next_steps": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "下一步建议"
+    },
+    "completed_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "$defs": {
+    "output_artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "required",
+        "satisfied",
+        "reason"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "path": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "satisfied": {
+          "type": "boolean"
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "delivery_readiness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "configured",
+        "mode",
+        "via",
+        "ready",
+        "required_signals",
+        "satisfied_signals",
+        "missing_signals",
+        "reason"
+      ],
+      "properties": {
+        "configured": {
+          "type": "boolean"
+        },
+        "mode": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "via": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "ready": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "required_signals": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "satisfied_signals": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "missing_signals": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "delivery_signal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "satisfied",
+        "reason"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "satisfied": {
+          "type": "boolean"
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schemas/state-index.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schemas/state-index.schema.json",
+  "title": "Harness State Index",
+  "description": "harness/state/index.json 的结构定义，记录当前活跃和挂起的任务索引。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "active_task_id",
+    "tasks"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "0.3"
+    },
+    "active_task_id": {
+      "type": ["string", "null"],
+      "description": "当前活跃任务 ID，无活跃任务时为 null"
+    },
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "task_id",
+          "intent",
+          "goal_summary",
+          "current_state",
+          "updated_at"
+        ],
+        "properties": {
+          "task_id": {
+            "type": "string"
+          },
+          "intent": {
+            "type": "string"
+          },
+          "goal_summary": {
+            "type": "string",
+            "description": "任务目标的简短摘要，用于快速识别"
+          },
+          "current_state": {
+            "type": "string",
+            "enum": [
+              "draft",
+              "needs_clarification",
+              "planned",
+              "in_progress",
+              "blocked",
+              "verifying",
+              "done",
+              "failed",
+              "suspended"
+            ]
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/task-draft.schema.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schemas/task-draft.schema.json",
+  "title": "Harness Task Draft",
+  "description": "Intake 阶段内部使用的任务草稿对象。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "source_input",
+    "intent",
+    "goal",
+    "scope",
+    "acceptance",
+    "constraints",
+    "mode",
+    "assumptions",
+    "open_questions",
+    "risk_signals",
+    "context_refs",
+    "next_action"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "0.3"
+    },
+    "source_input": {
+      "type": "string",
+      "minLength": 1
+    },
+    "intent": {
+      "type": "string",
+      "enum": [
+        "bug",
+        "feature",
+        "explore",
+        "refactor",
+        "prototype",
+        "unknown"
+      ]
+    },
+    "goal": {
+      "type": "string",
+      "minLength": 1
+    },
+    "scope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1
+    },
+    "acceptance": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1
+    },
+    "constraints": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": [
+        "delivery",
+        "explore",
+        "poc",
+        "unknown"
+      ]
+    },
+    "assumptions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "open_questions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "risk_signals": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "context_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "next_action": {
+      "type": "string",
+      "enum": [
+        "clarify",
+        "plan",
+        "observe",
+        "fail"
+      ]
+    },
+    "derived": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "risk_level": {
+          "type": "string",
+          "enum": [
+            "low",
+            "medium",
+            "high",
+            "unknown"
+          ]
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "draft",
+            "needs_clarification",
+            "planned",
+            "failed"
+          ]
+        }
+      }
+    }
+  }
+}

package/schemas/task-state.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness.local/schemas/task-state.schema.json",
+  "title": "Harness Task State",
+  "description": "持久化到 harness/state/tasks/<task_id>.json 的任务状态对象。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "task_id",
+    "current_phase",
+    "current_state",
+    "task_draft",
+    "evidence",
+    "open_questions",
+    "override_history",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "0.3"
+    },
+    "task_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9\\-]+$",
+      "minLength": 1
+    },
+    "current_phase": {
+      "type": "string",
+      "enum": [
+        "intake",
+        "clarify",
+        "plan",
+        "execute",
+        "verify",
+        "report",
+        "close"
+      ]
+    },
+    "current_state": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "needs_clarification",
+        "planned",
+        "in_progress",
+        "blocked",
+        "verifying",
+        "done",
+        "failed",
+        "suspended"
+      ]
+    },
+    "task_draft": {
+      "$ref": "./task-draft.schema.json"
+    },
+    "confirmed_contract": {
+      "description": "当合同闭合后填入，未闭合时为 null。",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "intent",
+            "goal",
+            "scope",
+            "acceptance"
+          ],
+          "properties": {
+            "intent": {
+              "type": "string"
+            },
+            "goal": {
+              "type": "string"
+            },
+            "scope": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "acceptance": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "title": {
+              "type": "string"
+            },
+            "constraints": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "verification": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "context_refs": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "id": {
+              "type": "string"
+            },
+            "mode": {
+              "type": "string"
+            },
+            "risk_level": {
+              "type": "string",
+              "enum": [
+                "low",
+                "medium",
+                "high"
+              ]
+            },
+            "evidence_required": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "type",
+          "content",
+          "timestamp"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "command_result",
+              "test_result",
+              "diff_summary",
+              "artifact",
+              "reasoning_note",
+              "manual_confirmation",
+              "audit_log"
+            ]
+          },
+          "content": {
+            "type": "string"
+          },
+          "exit_code": {
+            "type": "integer",
+            "description": "仅 command_result / test_result 时使用"
+          },
+          "passed": {
+            "type": "boolean",
+            "description": "仅 test_result 时使用"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      }
+    },
+    "open_questions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "override_history": {
+      "type": "array",
+      "items": {
+        "$ref": "./audit-log.schema.json#/$defs/audit_entry"
+      }
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/templates/bug.md

@@ -0,0 +1,58 @@
+---
+template_id: bug
+intent: bug
+goal: "<必填：一句话描述要修复的问题>"
+scope:
+  - "<必填：允许修改的模块、目录或文件>"
+acceptance:
+  - "<必填：什么算修复完成>"
+title: "<可选：任务标题>"
+constraints:
+  - "<可选：不能做什么>"
+verification:
+  - "<可选：验证命令或人工验证步骤>"
+context_refs:
+  - "<可选：日志、报错、相关设计文档>"
+mode: delivery
+risk_level: "<派生：由 harness 和 project config 推导>"
+evidence_required: []
+---
+
+# Bug 任务模板
+
+## 现象
+
+- 用户可见问题：
+- 触发条件：
+- 预期行为：
+
+## 已知事实
+
+- 已确认边界：
+- 已知不允许修改的部分：
+- 相关上下文：
+
+## 根因假设
+
+- 假设 1：
+- 假设 2：
+- 仍待确认的问题：
+
+## 执行计划
+
+- 最小修复路径：
+- 不做的改动：
+- 回滚方式：
+
+## 验证记录
+
+- 执行命令：
+- 结果摘要：
+- 缺失证据：
+
+## 输出结论
+
+- 根因判断：
+- 实际改动范围：
+- 剩余风险：
+- 下一步建议：