Use when you need `jjk-vkplan` in this repository. Source intent: 并行拆解入口:消费 /jjk-plan 产物并生成可执行卡片契约
参考规则: @dual-database
$jjk-vkplan 负责把规划产物转换为“可落卡、可执行、可追溯”的并行拆解产物。
必须存在:
workdocs/需求/<topic>/requirements.mdworkdocs/任务拆解/<YYYY-MM-DD_主题>/contracts/implementation_plan.mdimplementation_plan.planning_contractimplementation_plan.execution_contractimplementation_plan.task_to_pr_mappingimplementation_plan.implementation_tasks(含 task_id/feature_id/pr_id/risk_tags/mandatory_evidence/acceptance_cmds[*].kind)自动执行场景还必须具备 project_id(显式参数优先;仅可从同任务目录 _active_task.json 推断,不再依赖根索引)。
失败码:
VKPLAN_INPUT_NOT_READYVKPLAN_MISSING_PROJECT_IDVKPLAN_PR_MAPPING_MISSINGVKPLAN_EXECUTION_CONTRACT_MISSINGVKPLAN_TASKS_MISSING补充执行约束:执行命令时统一遵循 .cursor/rules/core.mdc 的“命令执行拆分”规则:单步单目标、失败只重跑当前步、长任务只轮询不重启、输出截断时优先拆短当前步。
至少检查:
planning_contract.execution_mode/card_order/cards/gate_contract;_active_task.json 与 vk_cards.json 是否冲突。从 planning_contract 继承并保持不变:
execution_modecard_ordercards[].card_idcards[].feature_idscards[].depends_oncards[].done_gatecards[].acceptance_checkstask_to_pr_mappingexecution_contract硬约束:
card_id/feature_id;depends_on;execution_mode=serial 必须保持单活卡推进语义;pr_id。cards[].done_gate 或 cards[].acceptance_checks。risk_tags/mandatory_evidence 只允许继承或细化,禁止删除或弱化。cross_card_closure.required=true 与 closure_owner。必须生成:
workdocs/任务拆解/<YYYY-MM-DD_主题>/parallel_plan.md(自动生成的人类可读总览,非机器真理源)workdocs/任务拆解/<YYYY-MM-DD_主题>/workstreams/WS-*.mdworkdocs/任务拆解/<YYYY-MM-DD_主题>/contracts/vk_cards.json最小字段要求:
card_id/feature_ids/task_ids/acceptance_checks/pr_id/pr_branch/risk_tags/mandatory_evidence;vk_cards.json 必须显式写入 execution_contract;parallel_plan.md 若生成,内容必须由 vk_cards.json 派生;gate_contract.mode=as_cards,Gate 必须实体化为卡片。cross_card_closure(未拆链时可 required=false)。python3 scripts/check_workflow_contract.py --mode plan_vk_coverage \
--task-split-dir <YYYY-MM-DD_主题> \
--output workdocs/任务拆解/<YYYY-MM-DD_主题>/reports/consumption_report.json
python3 scripts/check_workflow_contract.py --mode planning_temporal_gate \
--task-split-dir <YYYY-MM-DD_主题> \
--output workdocs/任务拆解/<YYYY-MM-DD_主题>/reports/temporal_gate_report.json
通过标准:
ok=truemissing_feature_ids=[]missing_task_ids=[]execution_contract_mismatch=[]acceptance_mapping_missing=[]missing_task_id_fields=[]empty_task_ids=[]clarify_plan_alignment.ok=trueVKPLAN_TEMPORAL_BLOCKER_FORBIDDENevidence_mapping_missing=[]cross_card_closure失败码:
VKPLAN_CONSUMPTION_GAPVKPLAN_EXECUTION_CONTRACT_MISMATCHVKPLAN_ACCEPTANCE_MAPPING_BROKENVKPLAN_TASK_IDS_REQUIREDCLARIFY_PLAN_ALIGNMENT_FAILEDPLAN_IMPLEMENTATION_DETAIL_INSUFFICIENTVKPLAN_TEMPORAL_BLOCKER_FORBIDDENVKPLAN_EVIDENCE_MAPPING_BROKENVKPLAN_DB_CHAIN_SPLIT_UNCLOSEDvk_cards.json.cards[*] 必须继承任务级 risk_tags 与 mandatory_evidence,不得仅保留 acceptance_checks。mandatory_evidence 必须与 task_ids 对应任务并集一致;不一致时输出 VKPLAN_EVIDENCE_MAPPING_BROKEN。risk_tags 命中 chat_db 或 data_db 且链路拆分到多卡,必须显式声明 cross_card_closure 并指定闭环卡。FAIL_FAST:VKPLAN_DB_CHAIN_SPLIT_UNCLOSED。拆卡后的唯一机器真理源为 vk_cards.json;parallel_plan.md 仅用于展示与兼容引用,不得再作为独立状态来源。
python3 scripts/set_active_task.py \
--task-split-dir <YYYY-MM-DD_主题> \
--project-id <project_id>
回读一致性要求(任务级真理源必须一致):
task_keytask_split_dirproject_id不一致时:VKPLAN_ACTIVE_TASK_MISMATCH。
主链路:
$jjk-plan -> $jjk-vkplan -> $jjk-cardrun -> $jjk-wtimp(executor_mode=cardrun_dispatch)
可选建卡链路(只做可见性):
$jjk-vktodo(create-only)
命中任一条件可启用 Team:
cards >= 8feature_id >= 12无 Team 能力时输出 TEAM_UNAVAILABLE_FALLBACK 并降级单代理。
planning_contract 就生成卡片。check_workflow_contract.py --mode plan_vk_coverage。task_ids 的卡片“先生成后补齐”。execution_contract 缺失时用默认值继续执行。使用 $jjk-vkplan 触发。目标是“最小流程生成可执行并行契约”。