Merge pull request 'Add StepSpec.Brief rendered as the task-instruction section of TASK.md' (#46) from feature/q3-step-brief into main

Merge pull request 'Add StepSpec.Brief rendered as the task-instruction section of TASK.md' (#46) from feature/q3-step-brief into main

squad/brief_test.go

@@ -0,0 +1,41 @@
+package squad
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// brief_test.go — Q3 WP1a：StepSpec.Brief 渲染进 TASK.md「任务指令」节。
+
+func TestStepBriefRendersIntoTaskFile(t *testing.T) {
+	rec := &promptRecordingBackend{prompts: map[string][]string{}}
+	engine := newRecordingEngine(t, rec, []StepSpec{
+		{ID: "s1", Role: "researcher", Title: "起草", Targets: []string{"output.md"},
+			Brief: "写一份关于「太空电梯」的简报，篇幅：短。\n必须包含单独一行「核对标记：P4」。"},
+	})
+	res, err := engine.Run(context.Background(), Goal{Text: "带任务指令"}, RunOptions{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Status != RunCompleted {
+		t.Fatalf("status = %s err = %v", res.Status, res.Error)
+	}
+	var prompt string
+	for _, p := range rec.prompts["01_researcher"] {
+		prompt += p
+	}
+	if !strings.Contains(prompt, "## 任务指令") {
+		t.Fatalf("TASK.md 缺任务指令节：%q", prompt)
+	}
+	if !strings.Contains(prompt, "核对标记：P4") {
+		t.Fatalf("任务指令正文缺失：%q", prompt)
+	}
+	// 指令节在期望产出之后、上下文表之前。
+	iOut := strings.Index(prompt, "期望产出")
+	iBrief := strings.Index(prompt, "## 任务指令")
+	iCtx := strings.Index(prompt, "## 任务上下文资源")
+	if !(iOut < iBrief && iBrief < iCtx) {
+		t.Fatalf("任务指令节位置错误：%d/%d/%d", iOut, iBrief, iCtx)
+	}
+}

squad/models.go

@@ -128,6 +128,10 @@ type StepSpec struct {
 	Branches []Branch `json:"branches,omitempty"`
 	// Handoff 非空 = 完成即把最终答案所有权移交给该角色（Q2 handoff 原语）。
 	Handoff string `json:"handoff,omitempty"`
+	// Brief 编译期任务指令（Q3 编译器）：非空时渲染进 TASK.md 的
+	// 「任务指令」节，位于标题/产出之后、上下文表之前。图步的富文本任务书
+	// 载体（此前只有 leader 委派有 briefing）。
+	Brief string `json:"brief,omitempty"`
 }
 
 // LoopSpec 是循环步的预算与停机条件（Q2）。

squad/workspace.go

@@ -189,6 +189,13 @@ func (e *WorkspaceEngine) writeTaskFile(subDir string, step *StepSpec, role Role
 	fmt.Fprintf(&b, "- 角色：%s（%s）\n", role.Name, role.Role)
 	fmt.Fprintf(&b, "- 期望产出：%v\n\n", step.Targets)
 
+	// 编译期任务指令（Q3）：编译器渲染好的富文本任务书，权威仅次于目标。
+	if strings.TrimSpace(step.Brief) != "" {
+		b.WriteString("## 任务指令\n\n")
+		b.WriteString(strings.TrimSpace(step.Brief))
+		b.WriteString("\n\n")
+	}
+
 	b.WriteString("## 任务上下文资源与权威等级（已快照到本目录，只引用本地路径）\n\n")
 	b.WriteString("| 资源路径 | 权威等级 | 用途说明 | 使用与引用指导 |\n|---|---|---|---|\n")
 	b.WriteString("| `context/goal.md` | **authoritative** | 运行目标 | 不可推翻 |\n")