@gajae-code/coding-agent 0.3.0 → 0.3.2

package/src/gjc-runtime/ultragoal-runtime.ts

@@ -1,10 +1,18 @@
 import * as crypto from "node:crypto";
 import * as path from "node:path";
-import type { WorkflowHudSummary } from "../skill-state/active-state";
+import { syncSkillActiveState, type WorkflowHudSummary } from "../skill-state/active-state";
 import { buildUltragoalHudSummary as buildWorkflowUltragoalHudSummary } from "../skill-state/workflow-hud";
+import { WORKFLOW_STATE_VERSION, workflowStateStoragePath } from "../skill-state/workflow-state-contract";
+import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
 import { renderUltragoalStatusMarkdown } from "./state-renderer";
-import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
+import {
+	appendJsonl,
+	readExistingStateForMutation,
+	writeArtifact,
+	writeJsonAtomic,
+	writeWorkflowEnvelopeAtomic,
+} from "./state-writer";
 
 export type UltragoalGjcGoalMode = "aggregate" | "per-story";
 export type UltragoalGoalStatus =
@@ -473,14 +481,145 @@ export function buildUltragoalHudSummary(
 		updatedAt: new Date().toISOString(),
 	});
 }
+function currentSessionId(): string | undefined {
+	const sessionId = process.env.GJC_SESSION_ID?.trim();
+	return sessionId || undefined;
+}
 
-function titleFromBrief(brief: string): string {
-	const firstLine = brief
+function ultragoalModeStateFromSummary(
+	summary: UltragoalStatusSummary,
+	latestLedger: UltragoalLedgerEvent | undefined,
+	existing: Record<string, unknown> | undefined,
+	sessionId: string | undefined,
+): Record<string, unknown> {
+	const updatedAt = new Date().toISOString();
+	return {
+		...(existing ?? {}),
+		skill: "ultragoal",
+		version: WORKFLOW_STATE_VERSION,
+		active: summary.exists && summary.status !== "complete",
+		current_phase: summary.status,
+		status: summary.status,
+		active_goal_id: summary.currentGoal?.id,
+		counts: summary.counts,
+		brief_path: summary.paths.briefPath,
+		ledger_path: summary.paths.ledgerPath,
+		goals_path: summary.paths.goalsPath,
+		latest_ledger_event: latestLedger?.event,
+		latest_ledger_event_id: latestLedger?.eventId,
+		updated_at: updatedAt,
+		...(sessionId ? { session_id: sessionId } : {}),
+	};
+}
+
+export async function syncUltragoalWorkflowState(cwd: string): Promise<void> {
+	const summary = await getUltragoalStatus(cwd);
+	const ledger = await readUltragoalLedger(cwd);
+	const latestLedger = ledger.at(-1);
+	const sessionId = currentSessionId();
+	const modeStateActive = summary.exists && summary.status !== "complete";
+	const syncModeState = async (targetSessionId: string | undefined): Promise<void> => {
+		const statePath = workflowStateStoragePath(cwd, "ultragoal", targetSessionId);
+		const existing = await readExistingStateForMutation(statePath);
+		if (existing.kind === "corrupt" && modeStateActive)
+			throw new Error(`Cannot sync corrupt ultragoal mode-state: ${existing.error}`);
+		const existingValue = existing.kind === "valid" ? existing.value : undefined;
+		await writeWorkflowEnvelopeAtomic(
+			statePath,
+			ultragoalModeStateFromSummary(summary, latestLedger, existingValue, targetSessionId),
+			{
+				cwd,
+				receipt: {
+					cwd,
+					skill: "ultragoal",
+					owner: "gjc-runtime",
+					command: "gjc ultragoal sync",
+					sessionId: targetSessionId,
+				},
+				audit: {
+					category: "state",
+					verb: "sync",
+					owner: "gjc-runtime",
+					skill: "ultragoal",
+					fromPhase: typeof existingValue?.current_phase === "string" ? existingValue.current_phase : undefined,
+					toPhase: summary.status,
+				},
+			},
+		);
+	};
+	await syncModeState(undefined);
+	if (sessionId) await syncModeState(sessionId);
+	await syncSkillActiveState({
+		cwd,
+		skill: "ultragoal",
+		active: summary.exists && summary.status !== "complete",
+		phase: summary.status,
+		sessionId: currentSessionId(),
+		hud: buildUltragoalHudSummary(summary, latestLedger),
+		source: "gjc-ultragoal",
+	});
+}
+
+async function syncUltragoalWorkflowStateBestEffort(cwd: string): Promise<void> {
+	try {
+		await syncUltragoalWorkflowState(cwd);
+	} catch {
+		// HUD and mode-state sync are best-effort and must not change command semantics.
+	}
+}
+
+function clampTitle(title: string): string {
+	return title.length > 80 ? `${title.slice(0, 77)}...` : title;
+}
+
+function firstNonEmptyLine(text: string): string | undefined {
+	return text
 		.split(/\r?\n/)
 		.map(line => line.trim())
 		.find(line => line.length > 0);
+}
+
+function titleFromBrief(brief: string): string {
+	const firstLine = firstNonEmptyLine(brief);
 	if (!firstLine) return "Complete ultragoal brief";
-	return firstLine.length > 80 ? `${firstLine.slice(0, 77)}...` : firstLine;
+	return clampTitle(firstLine);
+}
+
+// A reserved, column-0 (unindented) `@goal` line opens a story. The character
+// right after `@goal` must be `:`, an ASCII space or tab, or end-of-line, so
+// `@goalish`, `@goals:`, `@goal-foo`, `@goal.foo`, `@goal/foo`, a non-breaking
+// space, and indented or mid-line `@goal:` are all ordinary objective text and
+// never delimiters.
+const GOAL_DELIMITER = /^@goal(?::|[ \t]+|$)[ \t]*(.*)$/;
+
+interface ParsedGoal {
+	title: string;
+	objective: string;
+}
+
+function parseGoalsFromBrief(brief: string): ParsedGoal[] {
+	const sections: { title: string; body: string[] }[] = [];
+	let current: { title: string; body: string[] } | undefined;
+	for (const line of brief.split(/\r?\n/)) {
+		const match = GOAL_DELIMITER.exec(line);
+		if (match) {
+			current = { title: match[1].trim(), body: [] };
+			sections.push(current);
+			continue;
+		}
+		current?.body.push(line);
+	}
+	if (sections.length === 0) {
+		return [{ title: titleFromBrief(brief), objective: brief.trim() }];
+	}
+	return sections.map((section, index) => {
+		const body = section.body.join("\n").trim();
+		const title = section.title || firstNonEmptyLine(body) || "";
+		if (!title && !body) {
+			throw new Error(`ultragoal @goal block ${index + 1} has no title or objective`);
+		}
+		return { title: clampTitle(title), objective: body || title };
+	});
 }
 
 export async function createUltragoalPlan(input: {
@@ -491,21 +630,23 @@ export async function createUltragoalPlan(input: {
 	const brief = input.brief.trim();
 	if (!brief) throw new Error("ultragoal brief is required");
 	const now = new Date().toISOString();
+	// Parse the untrimmed brief so the raw-line delimiter contract holds: a
+	// leading-indented `@goal` on the first line must stay objective text rather
+	// than being promoted to column 0 by trimming.
+	const goals: UltragoalGoal[] = parseGoalsFromBrief(input.brief).map((goal, index) => ({
+		id: `G${String(index + 1).padStart(3, "0")}`,
+		title: goal.title,
+		objective: goal.objective,
+		status: "pending",
+		createdAt: now,
+		updatedAt: now,
+	}));
 	const plan: UltragoalPlan = {
 		version: 1,
 		brief,
 		gjcGoalMode: input.gjcGoalMode ?? "aggregate",
 		gjcObjective: DEFAULT_ULTRAGOAL_OBJECTIVE,
-		goals: [
-			{
-				id: "G001",
-				title: titleFromBrief(brief),
-				objective: brief,
-				status: "pending",
-				createdAt: now,
-				updatedAt: now,
-			},
-		],
+		goals,
 		createdAt: now,
 		updatedAt: now,
 	};
@@ -1235,16 +1376,26 @@ function renderStatus(summary: UltragoalStatusSummary, json: boolean): string {
 function renderCompleteHandoff(
 	result: { plan: UltragoalPlan; goal?: UltragoalGoal; allComplete: boolean },
 	json: boolean,
+	cwd: string,
 ): string {
-	if (json) return `${JSON.stringify(result, null, 2)}\n`;
-	if (result.allComplete) return "All ultragoal goals are complete.\n";
-	if (!result.goal) return "No schedulable ultragoal goal found.\n";
+	if (json) {
+		return renderCliWriteReceipt({
+			ok: true,
+			all_complete: result.allComplete,
+			next_action: result.allComplete ? "none" : "execute-goal",
+			goal_id: result.goal?.id,
+			goal_status: result.goal?.status,
+			gjc_objective: result.plan.gjcObjective,
+			goals_path: getUltragoalPaths(cwd).goalsPath,
+		});
+	}
+	if (result.allComplete) return "ultragoal complete all=true\n";
+	if (!result.goal) return "ultragoal next-action=none\n";
 	return [
-		`Ultragoal handoff: ${result.goal.id} — ${result.goal.title}`,
-		`Objective: ${result.goal.objective}`,
-		`GJC objective: ${result.plan.gjcObjective}`,
-		'Call goal({"op":"get"}); call goal({"op":"create","objective":"<printed objective>"}) only if no active GJC goal exists, then keep the GJC goal active while this Ultragoal story is verified and checkpointed.',
-		'Before checkpointing complete, obtain a passing architectReview (architecture/product/code CLEAR + APPROVE) and executorQa (e2e/red-team passed with contractCoverage, surfaceEvidence, adversarialCases, and artifactRefs matrix evidence), then checkpoint with --quality-gate-json and a fresh active goal snapshot; record blockers instead of completing on any finding, plan/code mismatch, shallow evidence, or missing artifact link; call goal({"op":"complete"}) only after the final aggregate receipt exists.',
+		`ultragoal next-action=execute-goal goal-id=${result.goal.id}`,
+		`objective=${result.goal.objective}`,
+		`gjc-objective=${result.plan.gjcObjective}`,
+		"checkpoint requires=architectReview:CLEAR+APPROVE,executorQa:passed",
 		"",
 	].join("\n");
 }
@@ -1253,29 +1404,40 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 	try {
 		const command = commandName(args);
 		const json = hasFlag(args, "--json");
+		let result: UltragoalCommandResult;
 		switch (command) {
 			case "status":
-				return { status: 0, stdout: renderStatus(await getUltragoalStatus(cwd), json) };
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				result = { status: 0, stdout: renderStatus(await getUltragoalStatus(cwd), json) };
+				break;
 			case "create":
 			case "create-goals": {
 				const mode = flagValue(args, "--gjc-goal-mode") === "per-story" ? "per-story" : "aggregate";
 				const plan = await createUltragoalPlan({ cwd, brief: await readBrief(cwd, args), gjcGoalMode: mode });
-				return {
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				result = {
 					status: 0,
 					createdPlan: true,
 					stdout: json
-						? `${JSON.stringify(plan, null, 2)}\n`
-						: `Created ultragoal plan with ${plan.goals.length} goal at ${getUltragoalPaths(cwd).goalsPath}.\n`,
+						? renderCliWriteReceipt({
+								ok: true,
+								goals_count: plan.goals.length,
+								goal_ids: plan.goals.map(goal => goal.id),
+								goals_path: getUltragoalPaths(cwd).goalsPath,
+							})
+						: `Created ultragoal plan with ${plan.goals.length} goal${plan.goals.length === 1 ? "" : "s"} at ${getUltragoalPaths(cwd).goalsPath}.\n`,
 				};
+				break;
 			}
-			case "complete-goals":
-				return {
+			case "complete-goals": {
+				const handoff = await startNextUltragoalGoal({ cwd, retryFailed: hasFlag(args, "--retry-failed") });
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				result = {
 					status: 0,
-					stdout: renderCompleteHandoff(
-						await startNextUltragoalGoal({ cwd, retryFailed: hasFlag(args, "--retry-failed") }),
-						json,
-					),
+					stdout: renderCompleteHandoff(handoff, json, cwd),
 				};
+				break;
+			}
 			case "checkpoint": {
 				const goalId = flagValue(args, "--goal-id") ?? "";
 				const status = parseGoalStatus(flagValue(args, "--status"));
@@ -1288,10 +1450,22 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					gjcGoalJson: flagValue(args, "--gjc-goal-json"),
 					qualityGateJson: flagValue(args, "--quality-gate-json"),
 				});
-				return {
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				const goal = plan.goals.find(item => item.id === goalId);
+				result = {
 					status: 0,
-					stdout: json ? `${JSON.stringify(plan, null, 2)}\n` : `Checkpointed ${goalId} as ${status}.\n`,
+					stdout: json
+						? renderCliWriteReceipt({
+								ok: true,
+								goal_id: goalId,
+								status,
+								goals_path: getUltragoalPaths(cwd).goalsPath,
+								completion_receipt_kind: goal?.completionVerification?.receiptKind,
+								quality_gate_hash: goal?.completionVerification?.qualityGateHash,
+							})
+						: `ultragoal checkpoint goal-id=${goalId} status=${status}\n`,
 				};
+				break;
 			}
 			case "steer": {
 				const kind = flagValue(args, "--kind");
@@ -1303,10 +1477,20 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					evidence: flagValue(args, "--evidence") ?? "",
 					rationale: flagValue(args, "--rationale") ?? "",
 				});
-				return {
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				const goal = plan.goals.at(-1);
+				result = {
 					status: 0,
-					stdout: json ? `${JSON.stringify(plan, null, 2)}\n` : "Accepted add_subgoal steering.\n",
+					stdout: json
+						? renderCliWriteReceipt({
+								ok: true,
+								kind,
+								goal_id: goal?.id,
+								goals_path: getUltragoalPaths(cwd).goalsPath,
+							})
+						: "Accepted add_subgoal steering.\n",
 				};
+				break;
 			}
 			case "record-review-blockers": {
 				const plan = await recordUltragoalReviewBlockers({
@@ -1317,11 +1501,20 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 					evidence: flagValue(args, "--evidence") ?? "",
 					gjcGoalJson: flagValue(args, "--gjc-goal-json"),
 				});
-				return { status: 0, stdout: json ? `${JSON.stringify(plan, null, 2)}\n` : "Recorded review blockers.\n" };
+				await syncUltragoalWorkflowStateBestEffort(cwd);
+				const goal = plan.goals.at(-1);
+				result = {
+					status: 0,
+					stdout: json
+						? renderCliWriteReceipt({ ok: true, goal_id: goal?.id, goals_path: getUltragoalPaths(cwd).goalsPath })
+						: "Recorded review blockers.\n",
+				};
+				break;
 			}
 			default:
 				return { status: 1, stderr: `Unknown gjc ultragoal command: ${command}\n` };
 		}
+		return result;
 	} catch (error) {
 		return { status: 1, stderr: `${error instanceof Error ? error.message : String(error)}\n` };
 	}

package/src/gjc-runtime/workflow-command-ref.ts

@@ -0,0 +1,239 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/active-state";
+
+export type CommandRefVisibility = "public" | "hidden" | "planned";
+export type CommandRefIncludeWhen = "implemented-only" | "planned";
+
+export interface CommandRefCommand {
+	tokens: string[];
+	rendered: string;
+	visibility: CommandRefVisibility;
+	includeWhen: CommandRefIncludeWhen;
+	note?: string;
+}
+
+export interface CommandRefExample {
+	label?: string;
+	bytes: string;
+}
+
+export interface CommandRefBridge {
+	from: string;
+	to: string;
+	rendered: string;
+}
+
+export interface CommandRefBlock {
+	skill: CanonicalGjcWorkflowSkill;
+	blockId: string;
+	sourcePath: string;
+	renderOrder: number;
+	markers: {
+		start: string;
+		end: string;
+	};
+	commands: CommandRefCommand[];
+	examples: CommandRefExample[];
+	aliasesAndBridges: CommandRefBridge[];
+	notes: string[];
+}
+
+export interface RenderedCommandRefBlock {
+	skill: CanonicalGjcWorkflowSkill;
+	blockId: string;
+	markers: CommandRefBlock["markers"];
+	bytes: string;
+}
+
+const skillPath = (skill: CanonicalGjcWorkflowSkill): string =>
+	`packages/coding-agent/src/defaults/gjc/skills/${skill}/SKILL.md`;
+
+const stateWrite = (skill: CanonicalGjcWorkflowSkill): CommandRefCommand => ({
+	tokens: ["gjc", "state", skill, "write", "--input", `'{"current_phase":"handoff"}'`, "--json"],
+	rendered: `gjc state ${skill} write --input '{"current_phase":"handoff"}' --json`,
+	visibility: "public",
+	includeWhen: "implemented-only",
+	note: "Marks the workflow ready for the skill-tool chain guard.",
+});
+
+const stateHandoff = (
+	skill: CanonicalGjcWorkflowSkill,
+	targets: readonly CanonicalGjcWorkflowSkill[],
+): CommandRefCommand => ({
+	tokens: ["gjc", "state", skill, "handoff", "--to", `<${targets.join("|")}>`, "--json"],
+	rendered: `gjc state ${skill} handoff --to <${targets.join("|")}> --json`,
+	visibility: "public",
+	includeWhen: "implemented-only",
+	note: "Bridge command run in-process by the skill tool after slash-skill dispatch.",
+});
+
+export const WORKFLOW_COMMAND_REF_BLOCKS: readonly CommandRefBlock[] = [
+	{
+		skill: "deep-interview",
+		blockId: "state",
+		sourcePath: skillPath("deep-interview"),
+		renderOrder: 10,
+		markers: {
+			start: "<!-- gjc:cmdref:start state -->",
+			end: "<!-- gjc:cmdref:end state -->",
+		},
+		commands: [
+			stateWrite("deep-interview"),
+			{
+				tokens: [
+					"gjc",
+					"deep-interview",
+					"--write",
+					"--stage",
+					"final",
+					"--slug",
+					"{slug}",
+					"--spec",
+					"<markdown-or-path>",
+					"--deliberate",
+					"--json",
+				],
+				rendered:
+					"gjc deep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json",
+				visibility: "public",
+				includeWhen: "implemented-only",
+				note: "Sanctioned deliberate deep-interview to ralplan bridge.",
+			},
+		],
+		examples: [
+			{
+				label: "handoff state write",
+				bytes: '```\ngjc state deep-interview write --input \'{"current_phase":"handoff"}\' --json\n```',
+			},
+			{
+				label: "deliberate bridge",
+				bytes: "```\ngjc \\\ndeep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json\n```",
+			},
+		],
+		aliasesAndBridges: [
+			{
+				from: "deep-interview",
+				to: "ralplan",
+				rendered:
+					"gjc deep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json",
+			},
+		],
+		notes: [
+			"Before invoking `/skill:ralplan`, `/skill:team`, or `/skill:ultragoal`, persist the final spec and mark deep-interview ready for handoff.",
+		],
+	},
+	{
+		skill: "ralplan",
+		blockId: "state",
+		sourcePath: skillPath("ralplan"),
+		renderOrder: 10,
+		markers: { start: "<!-- gjc:cmdref:start state -->", end: "<!-- gjc:cmdref:end state -->" },
+		commands: [stateWrite("ralplan"), stateHandoff("ralplan", ["team", "ultragoal"])],
+		examples: [
+			{
+				label: "handoff state write",
+				bytes: '```\ngjc state ralplan write --input \'{"current_phase":"handoff"}\' --json\n```',
+			},
+		],
+		aliasesAndBridges: [
+			{ from: "ralplan", to: "team|ultragoal", rendered: "gjc state ralplan handoff --to <team|ultragoal> --json" },
+		],
+		notes: [
+			"Before invoking `/skill:team` or `/skill:ultragoal`, mark ralplan ready for handoff so the skill tool's chain guard permits the transition.",
+		],
+	},
+	{
+		skill: "ultragoal",
+		blockId: "state",
+		sourcePath: skillPath("ultragoal"),
+		renderOrder: 10,
+		markers: { start: "<!-- gjc:cmdref:start state -->", end: "<!-- gjc:cmdref:end state -->" },
+		commands: [stateWrite("ultragoal"), stateHandoff("ultragoal", ["ralplan", "deep-interview"])],
+		examples: [
+			{
+				label: "handoff state write",
+				bytes: '```\ngjc state ultragoal write --input \'{"current_phase":"handoff"}\' --json\n```',
+			},
+		],
+		aliasesAndBridges: [
+			{
+				from: "ultragoal",
+				to: "ralplan|deep-interview",
+				rendered: "gjc state ultragoal handoff --to <ralplan|deep-interview> --json",
+			},
+		],
+		notes: [
+			"When the aggregate ultragoal is complete OR the user requests return to planning/clarification, mark ultragoal ready for handoff.",
+		],
+	},
+	{
+		skill: "team",
+		blockId: "state",
+		sourcePath: skillPath("team"),
+		renderOrder: 10,
+		markers: { start: "<!-- gjc:cmdref:start state -->", end: "<!-- gjc:cmdref:end state -->" },
+		commands: [stateWrite("team"), stateHandoff("team", ["ralplan", "deep-interview", "ultragoal"])],
+		examples: [
+			{
+				label: "handoff state write",
+				bytes: '```\ngjc state team write --input \'{"current_phase":"handoff"}\' --json\n```',
+			},
+		],
+		aliasesAndBridges: [
+			{
+				from: "team",
+				to: "ralplan|deep-interview|ultragoal",
+				rendered: "gjc state team handoff --to <ralplan|deep-interview|ultragoal> --json",
+			},
+		],
+		notes: [
+			"When the team task-set completes OR the user requests return to planning/persistence, mark team ready for handoff.",
+		],
+	},
+] as const;
+
+export function listCommandRefBlocks(skill?: CanonicalGjcWorkflowSkill): CommandRefBlock[] {
+	const blocks =
+		skill === undefined
+			? WORKFLOW_COMMAND_REF_BLOCKS
+			: WORKFLOW_COMMAND_REF_BLOCKS.filter(block => block.skill === skill);
+	return [...blocks].sort(
+		(a, b) => a.skill.localeCompare(b.skill) || a.renderOrder - b.renderOrder || a.blockId.localeCompare(b.blockId),
+	);
+}
+
+export function renderCommandRefBlock(skill: CanonicalGjcWorkflowSkill, blockId = "state"): RenderedCommandRefBlock {
+	const block = WORKFLOW_COMMAND_REF_BLOCKS.find(item => item.skill === skill && item.blockId === blockId);
+	if (block === undefined) throw new Error(`Unknown command-reference block: ${skill}/${blockId}`);
+
+	const lines: string[] = [];
+	lines.push(block.markers.start);
+	lines.push(`### Generated command reference: ${block.blockId}`);
+	lines.push("");
+	for (const note of block.notes) lines.push(note);
+	lines.push("");
+	lines.push("Commands:");
+	for (const command of block.commands.filter(
+		item => item.visibility === "public" && item.includeWhen === "implemented-only",
+	)) {
+		lines.push(`- \`${command.rendered}\``);
+		if (command.note !== undefined) lines.push(`  - ${command.note}`);
+	}
+	lines.push("");
+	lines.push("Examples:");
+	for (const example of block.examples) {
+		if (example.label !== undefined) lines.push(`- ${example.label}:`);
+		lines.push(example.bytes);
+	}
+	lines.push("");
+	lines.push("Aliases and bridges:");
+	for (const bridge of block.aliasesAndBridges) lines.push(`- ${bridge.from} -> ${bridge.to}: \`${bridge.rendered}\``);
+	lines.push(block.markers.end);
+	lines.push("");
+
+	return { skill, blockId: block.blockId, markers: block.markers, bytes: lines.join("\n") };
+}
+
+export function isCanonicalGjcWorkflowSkill(value: string): value is CanonicalGjcWorkflowSkill {
+	return (CANONICAL_GJC_WORKFLOW_SKILLS as readonly string[]).includes(value);
+}