@markjaquith/agency 2.60.0 → 2.61.0

package/src/workbase/frontmatter.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { parseFrontmatter } from "./frontmatter"
+import { formatWorkDocumentBody, parseFrontmatter } from "./frontmatter"
 
 describe("parseFrontmatter", () => {
 	test("parses YAML 1.2 frontmatter and body", async () => {
@@ -48,3 +48,20 @@ describe("parseFrontmatter", () => {
 		).rejects.toThrow("must begin with YAML frontmatter")
 	})
 })
+
+describe("formatWorkDocumentBody", () => {
+	test("generates explicit investigation sections", () => {
+		const body = formatWorkDocumentBody(
+			"Investigate Checkout",
+			"task",
+			"investigation",
+		)
+
+		expect(body).toContain("## Investigation Boundary")
+		expect(body).toContain("## Evidence")
+		expect(body).toContain("## Findings")
+		expect(body).toContain("## Recommendation")
+		expect(body).toContain("## Implementation Handoff")
+		expect(body).not.toContain("Describe the task outcome")
+	})
+})

package/src/workbase/frontmatter.ts

@@ -85,7 +85,35 @@ export const formatMarkdownDocument = (data: object, body: string) =>
 export const formatWorkDocumentBody = (
 	title: string,
 	kind: "epic" | "task" | "phase",
-) => `# ${title}
+	purpose?: "investigation" | "implementation",
+) =>
+	purpose === "investigation"
+		? `# ${title}
+
+## Investigation Boundary
+
+State the question, scope, and implementation excluded from this investigation.
+
+## Evidence
+
+Record inspected sources, commands, observations, and supporting links.
+
+## Findings
+
+Record findings, confidence, uncertainty, and relevant constraints.
+
+## Recommendation
+
+Recommend implementation, no change, or further investigation.
+
+## Implementation Handoff
+
+Record any distinct implementation task created from this investigation.
+
+## Important Decisions
+
+Record consequential decisions and their rationale.`
+		: `# ${title}
 
 ## Outcome
 

package/src/workbase/opencode-file.ts

@@ -10,7 +10,7 @@ const agencyPlanPrompt = `You are in Agency Plan mode. Think, read, search, and
 
 Start with \`agency context . --json\`. Use its document paths and revisions, then inspect the graph, related epics, tasks, phases, linked tickets, and repository declarations needed to understand the work. Use machine-readable Agency output when available instead of inferring structure from directory names.
 
-When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases.
+When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases, except when the user explicitly requests a new, separate, or follow-up item. Explicit-new intent overrides reuse of active and archived work even when the subject or suggested ID matches.
 
 Use the Agency CLI for full workbase orchestration when the plan requires it, including creating or updating related epics, tasks, and phases; moving tasks; maintaining dependencies; and changing lifecycle state. Use \`--if-revision\` with the revision returned by context for mutations that support it, and run \`agency validate\` after changing workbase structure. Use available ticket tools to inspect or update a linked external ticket when the plan requires it.
 

package/src/workbase/schemas.test.ts

@@ -64,6 +64,42 @@ describe("portable repository declarations", () => {
 })
 
 describe("body-of-work descriptions", () => {
+	test("decodes strict task purpose and handoff provenance", () => {
+		const handoff = {
+			source: { kind: "phase", taskId: "investigate", phaseId: "evidence" },
+			sourceRevision: "a".repeat(64),
+		}
+		const task = Schema.decodeUnknownSync(TaskFrontmatter, {
+			onExcessProperty: "error",
+		})({
+			ticketUrl: null,
+			purpose: "implementation",
+			handoff,
+			repo: "agency",
+			branch: "task/implement",
+			base: "main",
+			pr: null,
+		})
+		expect(task).toMatchObject({ purpose: "implementation", handoff })
+
+		for (const invalid of [
+			{ ...handoff, sourceRevision: "short" },
+			{ ...handoff, source: { kind: "phase", taskId: "investigate" } },
+			{ ...handoff, source: { kind: "task", taskId: "../unsafe" } },
+		]) {
+			expect(() =>
+				Schema.decodeUnknownSync(TaskFrontmatter, {
+					onExcessProperty: "error",
+				})({
+					ticketUrl: null,
+					purpose: "implementation",
+					handoff: invalid,
+					phases: [],
+				}),
+			).toThrow()
+		}
+	})
+
 	test("decodes review tasks strictly and rejects writable execution fields", () => {
 		const review = {
 			ticketUrl: null,

package/src/workbase/schemas.ts

@@ -46,7 +46,9 @@ const IsoTimestamp = NonEmptyString.pipe(
 
 const GitCommit = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{40}$/))
 
-const DocumentRevision = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{64}$/))
+export const DocumentRevision = Schema.String.pipe(
+	Schema.pattern(/^[a-f0-9]{64}$/),
+)
 
 export const ClaimRecord = Schema.Struct({
 	claimant: NonEmptyString,
@@ -155,6 +157,30 @@ const ExecutionUnit = {
 	completion: Schema.optional(CompletionRecord),
 }
 
+export const TaskPurpose = Schema.Literal("investigation", "implementation")
+
+export const TaskHandoffSource = Schema.Union(
+	Schema.Struct({
+		kind: Schema.Literal("task"),
+		taskId: EntityId,
+	}),
+	Schema.Struct({
+		kind: Schema.Literal("phase"),
+		taskId: EntityId,
+		phaseId: EntityId,
+	}),
+)
+
+export const TaskHandoff = Schema.Struct({
+	source: TaskHandoffSource,
+	sourceRevision: DocumentRevision,
+})
+
+const TaskMetadata = {
+	purpose: Schema.optional(TaskPurpose),
+	handoff: Schema.optional(TaskHandoff),
+}
+
 export const EpicFrontmatter = Schema.Struct({
 	ticketUrl: Url,
 	description: Description,
@@ -166,6 +192,7 @@ const SinglePhaseTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	...ExecutionUnit,
 })
 
@@ -173,6 +200,7 @@ const MultiPhaseTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	phases: Schema.Array(Dependency),
 })
 
@@ -221,6 +249,7 @@ const ReviewTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	review: ReviewRecord,
 	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
 	claim: Schema.optional(ClaimRecord),
@@ -254,6 +283,9 @@ export type PullRequestRecord = Schema.Schema.Type<typeof PullRequestRecord>
 export type ReviewSource = Schema.Schema.Type<typeof ReviewSource>
 export type ReviewRecord = Schema.Schema.Type<typeof ReviewRecord>
 export type CompletionRecord = Schema.Schema.Type<typeof CompletionRecord>
+export type TaskPurpose = Schema.Schema.Type<typeof TaskPurpose>
+export type TaskHandoffSource = Schema.Schema.Type<typeof TaskHandoffSource>
+export type TaskHandoff = Schema.Schema.Type<typeof TaskHandoff>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>