{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://gf.ai/schemas/workflow-contract-v1.1.json",
"title": "Workflow Contract",
"description": "Phase 间传递的结构化合同,用于 gf-workflow 四阶段编排器",
"type": "object",
"required": ["version", "workflow_id", "title", "mode", "skill_source", "created_at", "updated_at", "current_phase", "phases"],
"properties": {
"version": {
"type": "string",
"const": "1.1",
"description": "合同版本(兼容未来升级)"
},
"workflow_id": {
"type": "string",
"pattern": "^wf-\\d{4}-\\d{2}-\\d{2}-\\d{3}$",
"description": "唯一标识,格式:wf-YYYY-MM-DD-NNN"
},
"title": {
"type": "string",
"minLength": 1,
"description": "任务标题(从 Issue 标题同步)"
},
"mode": {
"type": "string",
"enum": ["full", "standard", "fast"],
"description": "full = 完整四阶段;standard = 中等复杂度;fast = 简单任务跳过非必需 Phase"
},
"skill_source": {
"type": "string",
"enum": ["superpowers", "mattpocock", "inline"],
"description": "启动时检测的技能来源;新合同必填,跨会话恢复沿用(恢复时重验在场性)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "创建时间 (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最后更新时间 (ISO 8601)"
},
"current_phase": {
"type": "integer",
"minimum": 1,
"maximum": 4,
"description": "当前 Phase 编号 (1-4)"
},
"phases": {
"type": "object",
"required": ["1", "2", "3", "4"],
"properties": {
"1": { "$ref": "#/$defs/phase" },
"2": { "$ref": "#/$defs/phase" },
"3": { "$ref": "#/$defs/phase" },
"4": { "$ref": "#/$defs/phase" }
},
"additionalProperties": false
},
"semantic_checks": {
"type": "array",
"maxItems": 128,
"items": { "$ref": "#/$defs/semantic_check" },
"description": "Optional semantic observations; never used by deterministic gates"
}
},
"additionalProperties": false,
"$defs": {
"semantic_check": {
"type": "object",
"required": ["checkedAt", "policyVersion", "phase", "ruleId", "matchedPaths", "finding"],
"properties": {
"checkedAt": { "type": "string", "format": "date-time" },
"policyVersion": { "type": "string" },
"phase": { "enum": ["plan", "execute", "deliver"] },
"ruleId": { "type": "string" },
"matchedPaths": { "type": "array", "items": { "type": "string" } },
"finding": {
"type": "object",
"required": ["ruleId", "conclusion", "confidence", "status", "advice", "hypothesis"],
"properties": {
"ruleId": { "type": "string" },
"conclusion": { "enum": ["possible_violation", "no_violation", "unavailable", "not_applicable"] },
"confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
"status": { "enum": ["observed", "warning", "needs_review", "unavailable", "not_applicable"] },
"advice": { "type": "string" },
"hypothesis": { "type": "boolean" }
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"phase": {
"type": "object",
"required": ["name", "status"],
"properties": {
"name": {
"type": "string",
"enum": ["Clarification", "Planning", "Execution", "Delivery"]
},
"status": {
"type": "string",
"enum": ["pending", "in_progress", "complete", "skipped"]
},
"started_at": {
"type": ["string", "null"],
"format": "date-time"
},
"completed_at": {
"type": ["string", "null"],
"format": "date-time"
},
"executor": {
"type": ["string", "null"]
},
"evidence": {
"type": "object",
"properties": {
"issue_url": { "type": "string" },
"comment_id": { "type": "string" },
"design_doc_path": {
"type": "string",
"description": "Path to design document generated by brainstorming (Phase 1)"
},
"spec_path": { "type": "string" },
"ticket_refs": {
"type": "array",
"items": { "type": "string" },
"description": "to-tickets 产出的票据清单(文件路径或 URL),mattpocock 路径 Phase 2 记录"
},
"user_approved": { "type": "boolean" },
"branch": { "type": "string" },
"pr_url": { "type": "string" },
"delivery_mode": {
"type": "string",
"enum": ["pr", "local_merge"],
"description": "Phase 3 交付方式;缺省视为 \"pr\"(向后兼容旧合同,字段本身无 default 关键字)"
},
"merge_commit": {
"type": "string",
"description": "本地合并时 (`delivery_mode == \"local_merge\"`) 产生的 merge commit SHA"
},
"tests_passed": { "type": "boolean" },
"merge_queued": {
"type": "boolean",
"description": "Phase 3 Step 5 是否已用 `gf pr merge --auto` 排队合并;false 表示需人工合并(如 GitCode 无排队能力)。仅作审计,不参与闸门判定"
},
"pipeline_ok": { "type": "boolean" },
"review_report_path": { "type": "string" },
"diff_review_status": {
"type": "string",
"enum": ["generated", "not_triggered", "failed"],
"description": "Phase 3 条件式 diff 审阅页结果;仅用于本地查看,不参与门禁"
},
"diff_review_path": {
"type": "string",
"description": "生成成功时主工作区 .cache/diff-review/ 下 HTML 的绝对路径"
},
"base_branch": {
"type": "string",
"description": "Branch the worktree was forked from (Phase 3)"
},
"worktree_path": {
"type": "string",
"description": "Absolute path to the git worktree created in Phase 3"
},
"worktree_preflight": {
"type": "string",
"enum": [
"clean",
"artifacts_carried",
"user_stashed",
"user_left_dirty",
"aborted"
],
"description": "Phase 3 worktree preflight 结局(见 references.md → Worktree Preflight)"
},
"unresolved_dirty_paths": {
"type": "array",
"items": { "type": "string" },
"description": "用户选择留在主工作区、未带入 worktree 的 B 桶路径(Phase 3 记档,供 Phase 4 与事后追溯)"
},
"branch_cleaned": {
"type": "boolean",
"description": "Whether Branch Finish cleanup was executed (Phase 4)"
},
"dogfooding_passed": {
"type": "boolean",
"description": "Whether dogfooding checklist passed (Phase 4)"
},
"phase4_steps_executed": {
"type": "array",
"items": { "type": "string" },
"description": "List of Phase 4 steps actually executed (for audit trail)"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
}