@gajae-code/coding-agent 0.1.1 → 0.1.2

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -65,14 +65,14 @@ Loop until `gjc ultragoal status` reports all goals complete:
 4. If no active GJC goal exists, call `create_goal({"objective":"<printed payload objective>"})` with the printed payload. In aggregate mode, if the same aggregate objective is already active, continue the current GJC story without creating a new GJC goal.
 5. Complete the current GJC story only.
 6. Run a completion audit against the story objective and real artifacts/tests.
-7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal({})` snapshot whose aggregate objective is still `active`. On the final story only, first run the mandatory final cleanup/review gate below; call `update_goal({"status":"complete"})` only after that gate is clean, then call `get_goal({})` again for a fresh `complete` snapshot.
-8. Checkpoint the durable ledger with that snapshot. Intermediate aggregate checkpoints use only `--gjc-goal-json`; final clean checkpoints also require `--quality-gate-json`:
-   `gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <get_goal-json-or-path> [--quality-gate-json <quality-gate-json-or-path>]`
+7. Before any `--status complete` checkpoint, run the mandatory final cleanup/review gate below. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal({})` snapshot whose aggregate objective is still `active`. On the final story only, call `update_goal({"status":"complete"})` after the gate is clean, then call `get_goal({})` again for a fresh `complete` snapshot.
+8. Checkpoint the durable ledger with that snapshot. Complete checkpoints require `--quality-gate-json`; the runtime hook rejects closure without a clean architect review:
+   `gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <get_goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>`
 9. If blocked or failed, checkpoint failure:
    `gjc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"`
-10. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
+11. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
    `gjc ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy GJC goal blocks create_goal in this thread>" --gjc-goal-json <get_goal-json-or-path>`
-11. Resume failed goals with `gjc ultragoal complete-goals --retry-failed`.
+12. Resume failed goals with `gjc ultragoal complete-goals --retry-failed`.
 
 ## Dynamic steering
 
@@ -120,6 +120,8 @@ If an Ultragoal request has no approved plan or consensus artifact, run `ralplan
 
 The Ultragoal leader owns `.gjc/ultragoal/goals.json` and `.gjc/ultragoal/ledger.jsonl`. Role agents return implementation/review evidence; they do not checkpoint Ultragoal or mutate goal state.
 
+For large subgoals with independent slices, the Ultragoal leader must spawn parallel `executor` subagents instead of doing serial solo work. Split only cleanly separable files/surfaces, give each executor bounded targets and acceptance criteria, and keep checkpoint ownership in the leader. Use `architect` / `critic` review lanes after integration; do not let worker agents mutate `.gjc/ultragoal` or call goal tools.
+
 ## Use Ultragoal and Team together
 
 Use ultragoal and team together for a durable Ultragoal story that benefits from one visible tmux worker session. Ultragoal remains leader-owned: `.gjc/ultragoal/goals.json` stores the story plan and `.gjc/ultragoal/ledger.jsonl` stores checkpoints. Team is the single-worker tmux execution engine and returns task/evidence status to the leader.
@@ -132,9 +134,9 @@ gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evid
 
 Workers do not own ultragoal goal state, do not create worker ultragoal ledgers, and do not checkpoint Ultragoal. Team launch remains explicit; Ultragoal does not auto-launch Team and performs no hidden goal mutation.
 
-## Mandatory final cleanup and review gate
+## Mandatory completion cleanup and review gate
 
-The final ultragoal story is not complete until the active agent has run the final quality gate:
+An ultragoal story cannot be checkpointed `complete` until the active agent has run the quality gate:
 
 1. Run targeted verification for the story.
 2. Run a cleanup/refactor review pass on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
@@ -142,28 +144,56 @@ The final ultragoal story is not complete until the active agent has run the fin
 4. Run a final code review pass. Clean means `codeReview.recommendation: "APPROVE"` and `codeReview.architectStatus: "CLEAR"`; `COMMENT`, `WATCH`, `REQUEST CHANGES`, and `BLOCK` are non-clean.
 5. If review is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
 
+1. Run targeted implementation verification for the story.
+2. Delegate an `architect` review covering all three lanes:
+   - architecture-side: system boundaries, layering, data/control flow, operational risks.
+   - product-side: user-visible behavior, acceptance criteria, edge cases, regressions.
+   - code-side: maintainability, tests, integration points, and unsafe shortcuts.
+3. Delegate an `executor` QA/red-team lane to build and run the e2e/read-teaming QA suite appropriate for the story. This lane must try to break the change, not just confirm the happy path.
+4. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `update_goal`. Record durable blocker work instead:
    ```sh
-   gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve final review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --gjc-goal-json <active-get-goal-json-or-path>
+   gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve verification blockers" --objective "<blocker-resolution objective>" --evidence "<architect/executor findings>" --gjc-goal-json <active-get-goal-json-or-path>
    ```
+5. Complete or steer through the blocker story, then rerun the full blocking verification loop. Repeat until all verifier lanes are clean.
+6. Only after the loop is clean, checkpoint the story as complete with a structured quality gate. The checkpoint creates a receipt; `goals.json.status` alone is not proof. Aggregate direct completion requires a fresh final aggregate receipt covering the full required-goal set before `update_goal({"status":"complete"})` is allowed.
 
-   This marks the current story `review_blocked`, appends a pending blocker-resolution story, keeps the GJC goal active, and lets `gjc ultragoal complete-goals` start the blocker next. In legacy per-story mode, the blocker may need an available GJC goal context because the old per-story GJC goal remains active/incomplete.
-
-6. If review is clean, call `update_goal({"status":"complete"})`, call `get_goal({})`, and checkpoint with a structured final gate:
-
-   ```sh
-   gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<tests/files/review evidence>" --gjc-goal-json <fresh-complete-get-goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>
-   ```
-
-`--quality-gate-json` must include:
+The native `checkpoint --status complete` command rejects missing or shallow gates. `--quality-gate-json` must include:
 
 ```json
 {
-  "aiSlopCleaner": { "status": "passed", "evidence": "cleaner report" },
-  "verification": { "status": "passed", "commands": ["npm test"], "evidence": "post-cleaner verification" },
-  "codeReview": { "recommendation": "APPROVE", "architectStatus": "CLEAR", "evidence": "final review synthesis" }
+  "architectReview": {
+    "architectureStatus": "CLEAR",
+    "productStatus": "CLEAR",
+    "codeStatus": "CLEAR",
+    "recommendation": "APPROVE",
+    "evidence": "architect review synthesis with architecture/product/code coverage",
+    "commands": ["architect review command or agent evidence id"],
+    "blockers": []
+  },
+  "executorQa": {
+    "status": "passed",
+    "e2eStatus": "passed",
+    "redTeamStatus": "passed",
+    "evidence": "executor-built e2e and red-team QA commands/results",
+    "e2eCommands": ["bun test:e2e"],
+    "redTeamCommands": ["bun test:red-team"],
+    "blockers": []
+  },
+  "iteration": {
+    "status": "passed",
+    "evidence": "blockers were absent or resolved and the full verification loop was rerun cleanly",
+    "fullRerun": true,
+    "rerunCommands": ["bun test:e2e", "bun test:red-team"],
+    "blockers": []
+  }
 }
 ```
 
+Receipts are freshness-scoped:
+- Per-goal receipts remain fresh for their target goal unless that goal, its blocker metadata, or its supersession metadata changes.
+- Normal later `goal_started` or clean receipt-backed `goal_checkpointed` events for other goals do not stale older per-goal receipts.
+- Appending required goals or changing final required-goal state stales final aggregate receipts. Final aggregate completion requires a fresh final aggregate receipt proving no incomplete, blocked, or `review_blocked` required goals remain.
+
 ## Constraints
 
 - The shell command cannot directly invoke interactive `/goal`; it emits a model-facing handoff for the active GJC agent.
@@ -171,6 +201,6 @@ The final ultragoal story is not complete until the active agent has run the fin
 - After a completed aggregate ultragoal run, clear the goal manually with `/goal clear` before starting another ultragoal run in the same session/thread.
 - Never call `create_goal` when `get_goal` reports a different active goal.
 - Never call `update_goal` unless the aggregate run or legacy per-story goal is actually complete.
-- In aggregate mode, intermediate story checkpoints require a matching `active` GJC goal snapshot; final story completion requires a matching `complete` snapshot after `update_goal`.
+- In aggregate mode, intermediate story checkpoints require a matching `active` GJC goal snapshot; final story checkpoint also uses the active snapshot and creates the final aggregate receipt. Only after that receipt exists may `update_goal({"status":"complete"})` reconcile the inline goal state.
 - Completion checkpoints require read-only goal snapshot reconciliation: pass fresh `get_goal` JSON/path with `--gjc-goal-json`; shell commands and hooks must not mutate goal state.
 - Treat `ledger.jsonl` as the durable audit trail; checkpoint after every success or failure.

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

@@ -0,0 +1,239 @@
+import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
+import {
+	computeUltragoalPlanGeneration,
+	hashStructuredValue,
+	readUltragoalLedger,
+	readUltragoalPlan,
+	type UltragoalCompletionVerification,
+	type UltragoalGoal,
+	type UltragoalLedgerEvent,
+	type UltragoalPlan,
+	type UltragoalReceiptKind,
+} from "./ultragoal-runtime";
+
+export type UltragoalGuardState =
+	| "inactive"
+	| "unrelated_goal"
+	| "active_verified_complete"
+	| "active_missing_receipt"
+	| "active_stale_receipt"
+	| "active_missing_final_receipt"
+	| "active_dirty_quality_gate"
+	| "active_review_blocked_unrecorded"
+	| "active_review_blocked_recorded"
+	| "unreadable_fail_closed";
+
+export interface UltragoalGuardDiagnostic {
+	state: UltragoalGuardState;
+	message: string;
+	goalId?: string;
+}
+
+export interface CurrentGoalLike {
+	objective: string;
+	status?: string;
+}
+
+function objectiveMatches(currentObjective: string, plan: UltragoalPlan): boolean {
+	const normalized = currentObjective.trim();
+	if (!normalized) return false;
+	if (normalized === plan.gjcObjective || normalized === DEFAULT_ULTRAGOAL_OBJECTIVE) return true;
+	if (plan.gjcObjectiveAliases?.some(alias => alias === normalized)) return true;
+	return plan.goals.some(goal => goal.objective === normalized);
+}
+
+function requiredGoals(plan: UltragoalPlan): UltragoalGoal[] {
+	return plan.goals.filter(goal => goal.status !== "superseded");
+}
+
+function findReceiptGoal(
+	plan: UltragoalPlan,
+	currentObjective: string,
+): { goal: UltragoalGoal; receiptKind: UltragoalReceiptKind } | null {
+	if (
+		currentObjective === plan.gjcObjective ||
+		currentObjective === DEFAULT_ULTRAGOAL_OBJECTIVE ||
+		plan.gjcObjectiveAliases?.some(alias => alias === currentObjective)
+	) {
+		const finalGoal = [...requiredGoals(plan)]
+			.reverse()
+			.find(goal => goal.completionVerification?.receiptKind === "final-aggregate");
+		return finalGoal ? { goal: finalGoal, receiptKind: "final-aggregate" } : null;
+	}
+	const storyGoal = plan.goals.find(goal => goal.objective === currentObjective);
+	return storyGoal ? { goal: storyGoal, receiptKind: "per-goal" } : null;
+}
+
+function findLedgerReceiptEvent(
+	ledger: readonly UltragoalLedgerEvent[],
+	receipt: UltragoalCompletionVerification,
+): UltragoalLedgerEvent | null {
+	return (
+		ledger.find(event => {
+			if (event.eventId !== receipt.checkpointLedgerEventId) return false;
+			if (event.event !== "goal_checkpointed") return false;
+			if (event.goalId !== receipt.goalId) return false;
+			const eventReceipt = event.completionVerification as UltragoalCompletionVerification | undefined;
+			return (
+				event.status === "complete" &&
+				eventReceipt?.receiptId === receipt.receiptId &&
+				eventReceipt.receiptKind === receipt.receiptKind &&
+				eventReceipt.planGeneration === receipt.planGeneration
+			);
+		}) ?? null
+	);
+}
+
+export function validateCompletionReceipt(input: {
+	plan: UltragoalPlan;
+	ledger: readonly UltragoalLedgerEvent[];
+	goal: UltragoalGoal;
+	receiptKind: UltragoalReceiptKind;
+}): UltragoalGuardDiagnostic {
+	const receipt = input.goal.completionVerification;
+	if (!receipt) {
+		return {
+			state: input.receiptKind === "final-aggregate" ? "active_missing_final_receipt" : "active_missing_receipt",
+			message: `Ultragoal ${input.goal.id} has no ${input.receiptKind} completion verification receipt.`,
+			goalId: input.goal.id,
+		};
+	}
+	if (
+		receipt.schemaVersion !== 1 ||
+		receipt.goalId !== input.goal.id ||
+		receipt.receiptKind !== input.receiptKind ||
+		!receipt.planGeneration ||
+		!receipt.checkpointLedgerEventId
+	) {
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt is malformed or stale.`,
+			goalId: input.goal.id,
+		};
+	}
+	const event = findLedgerReceiptEvent(input.ledger, receipt);
+	if (!event) {
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt ledger event is missing.`,
+			goalId: input.goal.id,
+		};
+	}
+	const generation = computeUltragoalPlanGeneration({
+		plan: input.plan,
+		ledger: input.ledger,
+		goal: input.goal,
+		receiptKind: input.receiptKind,
+		beforeStatus: receipt.goalStatusBeforeCheckpoint,
+		excludeEventId: receipt.checkpointLedgerEventId,
+	});
+	if (generation.planGeneration !== receipt.planGeneration) {
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt generation is stale.`,
+			goalId: input.goal.id,
+		};
+	}
+	if (hashStructuredValue(event.qualityGateJson) !== receipt.qualityGateHash) {
+		return {
+			state: "active_dirty_quality_gate",
+			message: `Ultragoal ${input.goal.id} receipt quality-gate hash does not match ledger.`,
+			goalId: input.goal.id,
+		};
+	}
+	if (input.goal.updatedAt !== receipt.verifiedAt) {
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} receipt target changed after verification.`,
+			goalId: input.goal.id,
+		};
+	}
+	if (input.receiptKind === "final-aggregate") {
+		const incomplete = requiredGoals(input.plan).filter(goal => goal.status !== "complete");
+		if (incomplete.length > 0) {
+			return {
+				state: "active_missing_final_receipt",
+				message: `Ultragoal final receipt is not valid while required goals remain incomplete: ${incomplete.map(goal => goal.id).join(", ")}.`,
+				goalId: input.goal.id,
+			};
+		}
+		const missingReceipts = requiredGoals(input.plan).filter(
+			goal => goal.id !== input.goal.id && !goal.completionVerification,
+		);
+		if (missingReceipts.length > 0) {
+			return {
+				state: "active_missing_receipt",
+				message: `Ultragoal final receipt is missing per-goal evidence for: ${missingReceipts.map(goal => goal.id).join(", ")}.`,
+				goalId: input.goal.id,
+			};
+		}
+	}
+	return {
+		state: "active_verified_complete",
+		message: `Ultragoal ${input.goal.id} has a fresh ${input.receiptKind} receipt.`,
+		goalId: input.goal.id,
+	};
+}
+
+export async function readUltragoalVerificationState(input: {
+	cwd: string;
+	currentGoal?: CurrentGoalLike | null;
+}): Promise<UltragoalGuardDiagnostic> {
+	const currentObjective = input.currentGoal?.objective?.trim() ?? "";
+	if (!currentObjective) return { state: "inactive", message: "No current goal objective is active." };
+	let plan: UltragoalPlan | null;
+	let ledger: UltragoalLedgerEvent[];
+	try {
+		plan = await readUltragoalPlan(input.cwd);
+		ledger = await readUltragoalLedger(input.cwd);
+	} catch (error) {
+		if (currentObjective === DEFAULT_ULTRAGOAL_OBJECTIVE) {
+			return {
+				state: "unreadable_fail_closed",
+				message: `Unable to read Ultragoal verification state: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+		return { state: "unrelated_goal", message: "Current goal is not an active Ultragoal objective." };
+	}
+	if (!plan) return { state: "inactive", message: "No Ultragoal plan exists." };
+	if (!objectiveMatches(currentObjective, plan))
+		return { state: "unrelated_goal", message: "Current goal is not an active Ultragoal objective." };
+	if (plan.goals.some(goal => goal.status === "review_blocked")) {
+		return {
+			state: "active_review_blocked_recorded",
+			message: "Ultragoal has recorded review blockers; complete blocker work and rerun verification.",
+		};
+	}
+	if (plan.goals.some(goal => goal.status === "blocked" || goal.status === "failed")) {
+		return {
+			state: "active_dirty_quality_gate",
+			message: "Ultragoal has blocked or failed goals; record blockers or rerun verification.",
+		};
+	}
+	const receiptTarget = findReceiptGoal(plan, currentObjective);
+	if (!receiptTarget) {
+		return {
+			state: "active_missing_final_receipt",
+			message: "Ultragoal aggregate completion requires a fresh final aggregate receipt.",
+		};
+	}
+	return validateCompletionReceipt({ plan, ledger, goal: receiptTarget.goal, receiptKind: receiptTarget.receiptKind });
+}
+
+export async function assertCanCompleteCurrentGoal(input: {
+	cwd: string;
+	currentGoal?: CurrentGoalLike | null;
+}): Promise<void> {
+	if (!input.cwd) return;
+	const diagnostic = await readUltragoalVerificationState(input);
+	if (["inactive", "unrelated_goal", "active_verified_complete"].includes(diagnostic.state)) return;
+	throw new Error(
+		`${diagnostic.message} Run strict \`gjc ultragoal checkpoint --status complete --quality-gate-json <file> --gjc-goal-json <file>\` first, or record review blockers and rerun verification.`,
+	);
+}
+
+export function isUltragoalBypassPrompt(prompt: string): boolean {
+	return /update_goal\s*\(|goal\s+complete|checkpoint[^\n]+--status\s+complete|skip\s+verification|weaken\s+verification|mark\s+.*complete/i.test(
+		prompt,
+	);
+}