@gajae-code/coding-agent 0.2.2 → 0.2.4

package/src/cli/update-cli.ts

@@ -12,7 +12,7 @@ import { $ } from "bun";
 import chalk from "chalk";
 import { theme } from "../modes/theme/theme";
 
-const REPO = "can1357/gajae-code";
+const RELEASE_REPO = "Yeachan-Heo/gajae-code";
 const PACKAGE = "@gajae-code/coding-agent";
 
 interface ReleaseInfo {
@@ -122,7 +122,7 @@ async function resolveUpdateTarget(): Promise<UpdateTarget> {
 
 	if (bunBinDir) return { method: "bun" };
 
-	throw new Error(`Could not resolve ${APP_NAME} binary path in PATH`);
+	throw new Error(formatUnsupportedTargetMessage(`Could not resolve ${APP_NAME} binary path in PATH`));
 }
 
 /**
@@ -166,10 +166,7 @@ function compareVersions(a: string, b: string): number {
 /**
  * Get the appropriate binary name for this platform.
  */
-function getBinaryName(): string {
-	const platform = process.platform;
-	const arch = process.arch;
-
+function getBinaryName(platform: NodeJS.Platform = process.platform, arch: string = process.arch): string {
 	let os: string;
 	switch (platform) {
 		case "linux":
@@ -182,7 +179,7 @@ function getBinaryName(): string {
 			os = "windows";
 			break;
 		default:
-			throw new Error(`Unsupported platform: ${platform}`);
+			throw new Error(formatUnsupportedTargetMessage(`Unsupported platform: ${platform}`));
 	}
 
 	let archName: string;
@@ -194,7 +191,7 @@ function getBinaryName(): string {
 			archName = "arm64";
 			break;
 		default:
-			throw new Error(`Unsupported architecture: ${arch}`);
+			throw new Error(formatUnsupportedTargetMessage(`Unsupported architecture: ${arch}`));
 	}
 
 	if (os === "windows") {
@@ -233,6 +230,65 @@ function printVerifiedVersion(expectedVersion: string): void {
 	console.log(chalk.green(`\n${theme.status.success} Updated to ${expectedVersion}`));
 }
 
+function formatBinaryInstallInstruction(platform: NodeJS.Platform = process.platform): string {
+	if (platform === "win32") {
+		return `For a supported binary install, reinstall with PowerShell: irm https://raw.githubusercontent.com/${RELEASE_REPO}/main/scripts/install.ps1 | iex`;
+	}
+	return `For a supported binary install, reinstall with: curl -fsSL https://raw.githubusercontent.com/${RELEASE_REPO}/main/scripts/install.sh | sh -s -- --binary`;
+}
+
+function formatManualUpdateInstructions(platform: NodeJS.Platform = process.platform): string {
+	return [
+		`If ${APP_NAME} was installed with Bun, run: bun install -g ${PACKAGE}@latest`,
+		`If ${APP_NAME} was installed with npm, pnpm, or another package manager, update it with that same manager.`,
+		formatBinaryInstallInstruction(platform),
+	].join("\n");
+}
+
+function formatUnsupportedTargetMessage(reason: string, platform: NodeJS.Platform = process.platform): string {
+	return `${reason}.\n${formatManualUpdateInstructions(platform)}`;
+}
+
+function buildReleaseBinaryUrl(
+	version: string,
+	platform: NodeJS.Platform = process.platform,
+	arch: string = process.arch,
+): string {
+	const binaryName = getBinaryName(platform, arch);
+	const tag = `v${version}`;
+	return `https://github.com/${RELEASE_REPO}/releases/download/${tag}/${binaryName}`;
+}
+
+function formatBinaryDownloadFailureMessage(
+	binaryName: string,
+	url: string,
+	status: string | number,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	return `Download failed for ${binaryName} from ${url}: ${status}.\n${formatManualUpdateInstructions(platform)}`;
+}
+
+export function formatBinaryDownloadFailureMessageForTest(
+	binaryName: string,
+	url: string,
+	status: string | number,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	return formatBinaryDownloadFailureMessage(binaryName, url, status, platform);
+}
+
+export function buildReleaseBinaryUrlForTest(
+	version: string,
+	platform: NodeJS.Platform = process.platform,
+	arch: string = process.arch,
+): string {
+	return buildReleaseBinaryUrl(version, platform, arch);
+}
+
+export function formatManualUpdateInstructionsForTest(platform: NodeJS.Platform = process.platform): string {
+	return formatManualUpdateInstructions(platform);
+}
+
 function formatVerificationFailure(result: InstalledVersionVerification, expectedVersion: string): string {
 	if (result.actual) {
 		return `${APP_NAME} at ${result.path} still reports ${result.actual} (expected ${expectedVersion})`;
@@ -250,11 +306,7 @@ async function printVerification(expectedVersion: string): Promise<void> {
 		return;
 	}
 	console.log(chalk.yellow(`\nWarning: ${formatVerificationFailure(result, expectedVersion)}`));
-	console.log(
-		chalk.yellow(
-			`You may need to reinstall: curl -fsSL https://raw.githubusercontent.com/can1357/gajae-code/main/scripts/install.sh | sh`,
-		),
-	);
+	console.log(chalk.yellow(formatManualUpdateInstructions()));
 }
 
 async function unlinkIfExists(filePath: string): Promise<void> {
@@ -314,8 +366,7 @@ async function updateViaBun(expectedVersion: string): Promise<void> {
  */
 async function updateViaBinaryAt(targetPath: string, expectedVersion: string): Promise<void> {
 	const binaryName = getBinaryName();
-	const tag = `v${expectedVersion}`;
-	const url = `https://github.com/${REPO}/releases/download/${tag}/${binaryName}`;
+	const url = buildReleaseBinaryUrl(expectedVersion);
 
 	const tempPath = `${targetPath}.new`;
 	const backupPath = `${targetPath}.bak`;
@@ -323,7 +374,7 @@ async function updateViaBinaryAt(targetPath: string, expectedVersion: string): P
 
 	const response = await fetch(url, { redirect: "follow" });
 	if (!response.ok || !response.body) {
-		throw new Error(`Download failed: ${response.statusText}`);
+		throw new Error(formatBinaryDownloadFailureMessage(binaryName, url, response.statusText || response.status));
 	}
 	const fileStream = fs.createWriteStream(tempPath, { mode: 0o755 });
 	await pipeline(response.body, fileStream);

package/src/cli.ts

@@ -44,6 +44,7 @@ const commands: CommandEntry[] = [
 		load: () => import("./commands/contribution-prep").then(m => m.default),
 	},
 	{ name: "deep-interview", load: () => import("./commands/deep-interview").then(m => m.default) },
+	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
 ];
 

package/src/commands/deep-interview.ts

@@ -1,10 +1,33 @@
-import { Command } from "@gajae-code/utils/cli";
+import { Command, Flags } from "@gajae-code/utils/cli";
 import { runNativeDeepInterviewCommand } from "../gjc-runtime/deep-interview-runtime";
 
 export default class DeepInterview extends Command {
 	static description = "Run native GJC deep-interview workflow";
 	static strict = false;
-	static examples = ['$ gjc deep-interview --standard "<idea>"'];
+	static flags = {
+		quick: Flags.boolean({ description: "Seed a quick deep-interview run" }),
+		standard: Flags.boolean({ description: "Seed a standard deep-interview run" }),
+		deep: Flags.boolean({ description: "Seed a deep deep-interview run" }),
+		threshold: Flags.string({ description: "Override ambiguity threshold for kickoff" }),
+		"threshold-source": Flags.string({ description: "Describe the threshold override source" }),
+		"session-id": Flags.string({
+			description: "Route state/spec handoff through a session-scoped .gjc state directory",
+		}),
+		write: Flags.boolean({ description: "Persist a final deep-interview spec through the sanctioned GJC CLI/API" }),
+		stage: Flags.string({ description: 'Spec stage for --write (currently "final")' }),
+		slug: Flags.string({ description: "Safe slug for .gjc/specs/deep-interview-<slug>.md" }),
+		spec: Flags.string({ description: "Final spec markdown or a path to the final spec markdown" }),
+		handoff: Flags.string({ description: 'After --write, hand off to a workflow target (currently "ralplan")' }),
+		deliberate: Flags.boolean({
+			description: "Shortcut for --write handoff to ralplan in deliberate consensus mode",
+		}),
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+	static examples = [
+		'$ gjc deep-interview --standard "<idea>"',
+		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md",
+		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --deliberate",
+	];
 
 	async run(): Promise<void> {
 		const result = await runNativeDeepInterviewCommand(this.argv, process.cwd());

package/src/commands/setup.ts

@@ -22,6 +22,7 @@ export default class Setup extends Command {
 		check: Flags.boolean({ char: "c", description: "Check if dependencies are installed" }),
 		force: Flags.boolean({ char: "f", description: "Overwrite existing default workflow skill files" }),
 		json: Flags.boolean({ description: "Output status as JSON" }),
+		preset: Flags.string({ description: "Provider preset: minimax, minimax-cn, or glm" }),
 		compat: Flags.string({ description: "Provider compatibility: openai or anthropic" }),
 		provider: Flags.string({ description: "Provider id to add to models.yml" }),
 		"base-url": Flags.string({ description: "Provider API base URL" }),
@@ -38,6 +39,7 @@ export default class Setup extends Command {
 				json: flags.json,
 				check: flags.check,
 				force: flags.force,
+				preset: flags.preset,
 				compat: flags.compat,
 				provider: flags.provider,
 				baseUrl: flags["base-url"],

package/src/commands/state.ts

@@ -11,6 +11,7 @@ export default class State extends Command {
 		"$ gjc state deep-interview read --json",
 		'$ gjc state ralplan write --input \'{"phase":"approval","active":true}\' --json',
 		"$ gjc state team contract",
+		"$ gjc state deep-interview handoff --to ralplan --json",
 	];
 
 	async run(): Promise<void> {

package/src/config/settings-schema.ts

@@ -843,6 +843,26 @@ export const SETTINGS_SCHEMA = {
 				"Maximum wait between retries, in ms. When the provider asks us to wait longer than this and no credential or model fallback succeeds, the request fails fast instead of sleeping (e.g. 3-hour Anthropic rate-limit windows).",
 		},
 	},
+	"retry.requestMaxRetries": {
+		type: "number",
+		default: 5,
+		ui: {
+			tab: "model",
+			label: "Provider Request Retries",
+			description:
+				"Maximum provider request retries before a stream is established. Counts retries, not the first attempt. Set to 0 to disable provider request retries.",
+		},
+	},
+	"retry.streamMaxRetries": {
+		type: "number",
+		default: 5,
+		ui: {
+			tab: "model",
+			label: "Provider Stream Retries",
+			description:
+				"Maximum provider stream replay retries for replay-safe transient stream failures. Counts retries, not the first attempt. Set to 0 to disable provider stream retries.",
+		},
+	},
 	"retry.fallbackChains": { type: "record", default: {} as Record<string, string[]> },
 	"retry.fallbackRevertPolicy": {
 		type: "enum",
@@ -1940,6 +1960,16 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"skill.enabled": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "tools",
+			label: "Skill",
+			description: "Enable the skill tool so the agent can chain into another available skill on its next turn",
+		},
+	},
+
 	// Fetching and browser
 	"fetch.enabled": {
 		type: "boolean",
@@ -2344,6 +2374,37 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"task.forkContext.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tasks",
+			label: "Fork Context for Subagents",
+			description:
+				"Allow explicitly opted-in subagents to start from a sanitized snapshot of parent context when both the agent and task item also opt in.",
+		},
+	},
+
+	"task.forkContext.maxMessages": {
+		type: "number",
+		default: 50,
+		ui: {
+			tab: "tasks",
+			label: "Fork Context Max Messages",
+			description: "Maximum parent messages copied into an explicitly opted-in subagent fork-context seed.",
+		},
+	},
+
+	"task.forkContext.maxTokens": {
+		type: "number",
+		default: 0,
+		ui: {
+			tab: "tasks",
+			label: "Fork Context Max Tokens",
+			description: "Approximate token cap for fork-context seeds. 0 uses 25% of the target model context window.",
+		},
+	},
+
 	"task.maxRecursionDepth": {
 		type: "number",
 		default: 2,
@@ -2792,6 +2853,8 @@ export interface RetrySettings {
 	maxRetries: number;
 	baseDelayMs: number;
 	maxDelayMs: number;
+	requestMaxRetries: number;
+	streamMaxRetries: number;
 }
 
 export interface MemoriesSettings {

package/src/defaults/gjc/skills/deep-interview/SKILL.md

@@ -39,6 +39,7 @@ Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demo
 
 <Execution_Policy>
 - Ask ONE question at a time -- never batch multiple questions
+- Preserve the user/session language for every user-facing announcement, topology confirmation, option label, and interview question when state includes `language.instruction`; for example Korean initial ideas must receive Korean deep-interview questions unless the user explicitly requests another language
 - Target the WEAKEST clarity dimension with each question
 - Before Round 1 ambiguity scoring, run a one-time Round 0 topology enumeration gate that confirms the top-level component list and locks it into state
 - Make weakest-dimension targeting explicit every round: name the weakest dimension, state its score/gap, and explain why the next question is aimed there
@@ -54,6 +55,15 @@ Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demo
 - Challenge agents activate at specific round thresholds to shift perspective
 </Execution_Policy>
 
+<Internal_Auto_Mode_Protocol>
+- `auto-research-greenfield.md` and `auto-answer-uncertain.md` are internal prompt fragments loaded on demand with bundle metadata `kind: "skill-fragment"`; they are not public skills, are never slash-command/discoverable, and must not be registered through any `skill://` route.
+- Load fragments only for the specific hook that needs them, with forked inherited context kept read-only and prompt-budgeted; summarize active interview context before spawning the architect if the payload is large.
+- Auto-mode architects are read-only: no code edits, no `.gjc/` mutation, no workflow chaining, no formatters, and no execution delegation.
+- Validate every fragment response before using it: required sections must be present, candidates/answer must match the requested shape, rationale must cite available context, confidence must be explicit, and insufficient-context fallbacks must be honored.
+- If architect spawn, fragment loading, or response validation fails, continue the normal manual interview path silently and record an internal audit note in state by incrementing `architect_failures`; do not expose tool noise to the user unless it changes the next user-facing question.
+- Track `auto_researched_rounds`, `auto_answered_rounds`, and `architect_failures` in state and final spec metadata.
+</Internal_Auto_Mode_Protocol>
+
 
 
 <Steps>
@@ -83,6 +93,7 @@ Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThreshold
    - Substitute `<resolvedThreshold>`, `<resolvedThresholdPercent>`, and `<resolvedThresholdSource>` throughout the remaining instructions before continuing.
    - Include `threshold_source` in the first `gjc state write` payload and preserve it on later state updates; do not edit `.gjc/state` files directly unless an explicit force override is active.
    - Include both threshold and source in the final spec metadata.
+- Read any `language` object from active deep-interview state and carry `language.instruction` forward mechanically. If absent, infer the user/session language from `{{ARGUMENTS}}` only when it is obvious. Do not surprise a Korean session with English questions.
 
 ## Phase 1: Initialize
 
@@ -133,7 +144,10 @@ Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThreshold
       "last_targeted_component_id": null
     },
     "challenge_modes_used": [],
-    "ontology_snapshots": []
+    "ontology_snapshots": [],
+    "auto_researched_rounds": [],
+    "auto_answered_rounds": [],
+    "architect_failures": 0
   }
 }
 ```
@@ -170,7 +184,7 @@ I'm reading this as {N} top-level component(s):
 Is that topology right? Should any component be added, removed, merged, split, or explicitly deferred?
 ```
 
-Options should include contextually relevant choices such as **Looks right**, **Add/remove/merge components**, **Defer one or more components**, plus free-text. This is the only pre-scoring question and preserves the one-question-per-round rule.
+Options should include contextually relevant choices such as **Looks right**, **Add/remove/merge components**, **Defer one or more components**, plus free-text, translated/localized according to `language.instruction` when present. This is the only pre-scoring question and preserves the one-question-per-round rule.
 
 3. **Lock topology into state** after the answer. Store a normalized component list and confirmation timestamp:
 
@@ -246,9 +260,15 @@ If any prompt input is too large, summarize it first and then continue from the
 | Context Clarity (brownfield) | "How does this fit?" | "I found JWT auth middleware in `src/auth/` (pattern: passport + JWT). Should this feature extend that path or intentionally diverge from it?" |
 | Scope-fuzzy / ontology stress | "What IS the core thing here?" | "You have named Tasks, Projects, and Workspaces across the last rounds. Which one is the core entity, and which are supporting views or containers?" |
 
+### Step 2a′: Auto-Research Greenfield Questions
+
+When the next question is for a greenfield interview and is tagged `research: true`, load `auto-research-greenfield.md` as an internal `kind: "skill-fragment"` prompt for a fork-context architect before Step 2b. Pass only the tagged question, locked topology summary, prompt-safe initial idea, trimmed prior decisions/gaps, and relevant constraints. The architect must return 2-3 ranked candidates with rationale, confidence, and fallback notes. Validate the shape before use; if valid, incorporate the candidates as concise answer options or context for the single user-facing question and append the round number to `auto_researched_rounds`. If invalid or unavailable, fall back silently to the normal generated question and increment `architect_failures`.
+
+Auto-research must never add a public skill entrypoint, never be slash-command/discoverable, never register a `skill://` handler, and never alter the one-question-per-round rule.
+
 ### Step 2b: Ask the Question
 
-Use the `ask` tool with the generated question. Present it clearly with the current ambiguity context:
+Use the `ask` tool with the generated question. Before rendering the prompt/options, apply `language.instruction` from state when present so the entire user-facing question remains in the preserved session language. Present it clearly with the current ambiguity context:
 
 ```
 Round {n} | Component: {target_component_name} | Targeting: {weakest_dimension} | Why now: {one_sentence_targeting_rationale} | Ambiguity: {score}%
@@ -258,10 +278,18 @@ Round {n} | Component: {target_component_name} | Targeting: {weakest_dimension}
 
 Options should include contextually relevant choices plus free-text.
 
+### Step 2b′: Auto-Answer Opted-Out Questions
+
+After the `ask` tool resolves and before ambiguity scoring, if the user opts out of answering the current question or explicitly asks the agent to decide, load `auto-answer-uncertain.md` as an internal `kind: "skill-fragment"` prompt for a fork-context architect. Pass the opted-out question, prompt-safe transcript summary, locked topology, current scores/gaps, and any auto-research candidates used for the round. The architect must return exactly one decisive answer with rationale, confidence, and explicit uncertainty. Validate the response shape before using it; if valid, record it as the tentative answer for scoring, append the round number to `auto_answered_rounds`, and mark the transcript answer as architect-assisted.
+
+Auto-answer has a clarity cap: unless the architect confidence is `high` and uncertainty is negligible, no dimension score improved solely by the auto-answer may exceed `0.85`. If the auto-answer would make ambiguity cross the resolved threshold, ask the user for threshold-crossing confirmation before Phase 4: present the tentative assumption and require explicit confirmation, revision, or continued questioning. On architect failure or invalid response, continue with the user's opt-out as an unresolved gap, increment `architect_failures`, and do not block the interview.
+
 ### Step 2c: Score Ambiguity
 
 After receiving the user's answer, score clarity across all dimensions.
 
+If the round used an auto-answer, include the architect answer, rationale, confidence, and uncertainty in the scoring prompt. Apply the Step 2b′ clarity cap mechanically before calculating ambiguity, and treat any low-confidence or insufficient-context auto-answer as an unresolved gap rather than user-confirmed truth.
+
 **Scoring prompt** (use opus model, temperature 0.1 for consistency):
 
 ```
@@ -355,7 +383,7 @@ Round {n} complete.
 
 ### Step 2e: Update State
 
-Update interview state with the new round, global scores, per-component `topology.components[].clarity_scores`, `topology.components[].weakest_dimension`, ontology snapshot, and `topology.last_targeted_component_id` via `gjc state write`; never patch `.gjc/state` directly unless an explicit force override is active.
+Update interview state with the new round, global scores, per-component `topology.components[].clarity_scores`, `topology.components[].weakest_dimension`, ontology snapshot, `topology.last_targeted_component_id`, `auto_researched_rounds`, `auto_answered_rounds`, and `architect_failures` via `gjc state write`; never patch `.gjc/state` directly unless an explicit force override is active.
 
 ### Step 2f: Check Soft Limits
 
@@ -389,8 +417,9 @@ When ambiguity ≤ threshold (or hard cap / early exit):
 1. **Generate the specification** using opus model with the prompt-safe transcript. If the full interview transcript or initial context is too large, include the summary plus all concrete decisions, acceptance criteria, unresolved gaps, and ontology snapshots; never overflow the prompt with raw oversized context.
 2. **Write the final spec through the workflow CLI**: persist the artifact at `.gjc/specs/deep-interview-{slug}.md`
    - Always use this exact final spec path. Do not write temporary working files to the repo root or other ad hoc paths; repos may allowlist `.gjc/` for planning artifacts while protecting product branches.
-   - Use the GJC workflow/state CLI for artifact and state persistence; direct `.gjc/` file edits are forbidden unless an explicit force override is active.
+   - Use the native deep-interview write command with `--write --stage final --slug {slug} --spec <markdown-or-path> [--json]` for artifact and state persistence; direct `.gjc/` file edits are forbidden unless an explicit force override is active.
    - Persist the final `spec_path` in state when available so downstream skills and resumed sessions can pass the artifact path explicitly.
+   - If the user preselected the deliberate ralplan path, use the native deep-interview write command with `--write --stage final --slug {slug} --spec <markdown-or-path> --deliberate [--json]` so the final spec is persisted before deep-interview hands off to ralplan.
 
 Spec structure:
 
@@ -407,6 +436,9 @@ Spec structure:
 - Threshold Source: <resolvedThresholdSource>
 - Initial Context Summarized: {yes|no}
 - Status: {PASSED | BELOW_THRESHOLD_EARLY_EXIT}
+- Auto-Researched Rounds: {auto_researched_rounds}
+- Auto-Answered Rounds: {auto_answered_rounds}
+- Architect Failures: {architect_failures}
 
 ## Clarity Breakdown
 | Dimension | Score | Weight | Weighted |
@@ -515,6 +547,23 @@ After the spec is written, mark it `pending approval` and present execution opti
 
 **IMPORTANT:** On explicit execution selection, **MUST** use the chosen bundled GJC workflow skill entrypoint (`/skill:ralplan` or `/skill:team`) inside the agent session. `gjc ralplan` is a native CLI that accepts the documented skill flags and seeds local `.gjc/state` receipts; agent sessions should still drive the consensus loop through `/skill:ralplan`. `gjc team` is a native tmux runtime command and may be used only when the Team workflow explicitly requires the CLI runtime. Do NOT implement directly. The deep-interview agent is a requirements agent, not an execution agent. If oversized initial context was summarized, pass the spec and prompt-safe summary forward, not the raw oversized source material. Without explicit execution selection, stop with the spec marked `pending approval`.
 
+### Phase 5b: Handoff before chain
+
+Before invoking `/skill:ralplan`, `/skill:team`, or `/skill:ultragoal`, the final spec must already be persisted through the native deep-interview write command. For ordinary user-selected handoff, mark deep-interview ready for the skill tool's chain guard:
+
+```
+gjc state deep-interview write --input '{"current_phase":"handoff"}' --json
+```
+
+For a preselected deliberate ralplan path, prefer the single sanctioned bridge command instead:
+
+```
+gjc \
+deep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json
+```
+
+That command persists `.gjc/specs/deep-interview-{slug}.md`, seeds ralplan in deliberate mode, and performs the safe deep-interview → ralplan state handoff. Skipping spec persistence leaves the Phase 5 chain blocked by design.
+
 ### Approval-Gated Refinement Path (Recommended)
 
 ```
@@ -551,6 +600,8 @@ Skipping any stage is possible but reduces quality assurance:
 - Use the GJC workflow CLI to save the final spec at `.gjc/specs/deep-interview-{slug}.md` exactly; do not use `write`, `edit`, or `ast_edit` directly on `.gjc/` paths without force override.
 - Use public GJC workflow entrypoints to bridge to ralplan/team only after explicit execution approval — never implement directly
 - Challenge agent modes are prompt injections, not separate agent spawns
+- Use internal fragment auto-modes only at their documented hooks: `auto-research-greenfield.md` between Step 2a and 2b for greenfield `research: true` questions, and `auto-answer-uncertain.md` as Step 2b′ after `ask` resolves and before scoring.
+- Fragment auto-modes are loaded on demand as `kind: "skill-fragment"`; they are not public workflow skills, not slash-command/discoverable, and not `skill://` registrations.
 </Tool_Usage>
 
 <Examples>
@@ -685,6 +736,8 @@ Why bad: 45% ambiguity means nearly half the requirements are unclear. The mathe
 - [ ] Multi-component interviews rotate targeting across active components when N > 1
 - [ ] Spec includes Topology section with confirmed active components and user-confirmed deferrals
 - [ ] Spec includes Ontology (Key Entities) table and Ontology Convergence section
+- [ ] Internal auto-mode fragments, when used, were loaded only on demand as non-public `kind: "skill-fragment"` prompts; responses were validated, failures incremented `architect_failures`, and final metadata includes `auto_researched_rounds`, `auto_answered_rounds`, and `architect_failures`
+- [ ] Auto-answer threshold crossing, if any, received explicit user confirmation before spec crystallization
 </Final_Checklist>
 
 <Advanced>

package/src/defaults/gjc/skills/deep-interview/auto-answer-uncertain.md

@@ -0,0 +1,37 @@
+# Deep Interview Auto Answer: Uncertain User Opt-Out
+
+You are a read-only architect helping the deep-interview workflow resolve one question after the user opted out, answered with uncertainty, or explicitly asked the agent to decide.
+
+Inherited context is read-only background. Do not edit code, write files, mutate `.gjc/` state, run formatters, invoke workflow handoffs, or implement anything. Use only inherited context, the opted-out question, prior interview decisions, topology/ontology notes, confirmed constraints, and read-only repo/context inspection if available.
+
+Keep the response compact enough to fit into ambiguity scoring.
+
+## Task
+
+Provide one decisive answer the parent workflow can tentatively carry forward. Choose the most conservative answer that preserves user intent, avoids irreversible assumptions, and keeps the interview moving.
+
+## Response Shape
+
+Respond with only this JSON object:
+
+```json
+{
+  "status": "answered",
+  "answer": "One concise decisive answer phrased as the assumption Deep Interview should carry.",
+  "rationale": [
+    "Context or repo fact supporting the answer."
+  ],
+  "confidence": "high|medium|low",
+  "uncertainty": "Explicit remaining uncertainty, or null if negligible."
+}
+```
+
+Rules:
+- `answer` must be non-empty and must not contradict confirmed user constraints.
+- `rationale` must contain 2-4 bullets citing inherited context, confirmed constraints, or repo facts available in the prompt.
+- `confidence` must be `high`, `medium`, or `low`.
+- Use `uncertainty` whenever context is thin, ambiguous, or depends on a product choice the transcript has not settled.
+
+## Fallback
+
+If inherited context is insufficient for a defensible decisive answer, do not guess. Return the safest reversible default if one exists, mark confidence `low`, set `uncertainty` to `Insufficient context for a reliable answer: <missing decision or evidence>`, and clearly identify what the user must confirm before execution approval.

package/src/defaults/gjc/skills/deep-interview/auto-research-greenfield.md

@@ -0,0 +1,42 @@
+# Deep Interview Auto Research: Greenfield
+
+You are a read-only architect helping the deep-interview workflow evaluate one greenfield question tagged `research: true`.
+
+Inherited context is read-only background. Do not edit code, write files, mutate `.gjc/` state, run formatters, invoke workflow handoffs, or implement anything. Use only inherited context, the tagged question, prior interview decisions, topology/ontology notes, confirmed constraints, and read-only repo/context inspection if available.
+
+Keep the response compact enough to fit back into the parent interview prompt.
+
+## Task
+
+Return 2-3 ranked candidate answers for the tagged greenfield question. Candidates must be concrete, mutually distinct, consistent with confirmed constraints, and useful as answer options or context for the next single Socratic question.
+
+## Response Shape
+
+Respond with only this JSON object:
+
+```json
+{
+  "status": "answered",
+  "candidates": [
+    {
+      "rank": 1,
+      "answer": "Concise candidate answer.",
+      "rationale": "Why this candidate fits the inherited context and confirmed constraints.",
+      "risks_or_tradeoffs": "Main risk, tradeoff, or caveat for this candidate.",
+      "confidence": "high|medium|low"
+    }
+  ],
+  "recommendation": "One sentence naming the strongest candidate and why it should be offered first.",
+  "follow_up_gap": "One sentence naming the remaining uncertainty the user should still confirm."
+}
+```
+
+Rules:
+- `candidates` must contain 2 or 3 entries when context supports that many.
+- `rank` starts at 1 and increases by 1.
+- `confidence` must be `high`, `medium`, or `low`.
+- Every rationale must cite inherited context, confirmed constraints, or repo facts available in the prompt.
+
+## Fallback
+
+If inherited context is insufficient to produce at least two meaningful candidates, say so explicitly in `follow_up_gap`, return the best single defensible candidate only if one exists, mark confidence `low`, and name the missing context. Do not fabricate certainty.

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

@@ -72,6 +72,14 @@ The consensus workflow:
 7. *(--interactive only)* User chooses: Approve team execution, Request changes, or Reject
 8. *(--interactive only)* On approval: invoke `/skill:team` for execution -- never implement directly
 
+   Before invoking `/skill:team` or `/skill:ultragoal`, mark ralplan ready for handoff so the skill tool's chain guard permits the transition:
+
+   ```
+   gjc state ralplan write --input '{"current_phase":"handoff"}' --json
+   ```
+
+   The skill tool then dispatches the execution skill same-turn and runs `gjc state ralplan handoff --to <team|ultragoal> --json` in-process to atomically demote ralplan, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.
+
 > **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent Task calls in the same parallel batch. Always await the Architect result before issuing the Critic Task.
 
 Follow the Plan skill's full documentation for consensus mode details.

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

@@ -394,3 +394,13 @@ Two cleanup paths exist and must not be confused:
 **Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
 
 **Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
+
+## Handoff back to planning or persistence
+
+When the team task-set completes OR the user requests return to planning/persistence, mark team ready for handoff so the skill tool's chain guard permits the transition:
+
+```
+gjc state team write --input '{"current_phase":"handoff"}' --json
+```
+
+The skill tool then dispatches `/skill:ralplan`, `/skill:deep-interview`, or `/skill:ultragoal` same-turn and runs `gjc state team handoff --to <ralplan|deep-interview|ultragoal> --json` in-process to atomically demote team, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.

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

@@ -11,7 +11,7 @@ Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durabl
 
 ## Purpose
 
-`ultragoal` turns a brief into repo-native artifacts and then drives a GJC goal safely through the unified `goal` tool. New plans default to a stable pointer-style aggregate GJC goal for the whole durable plan in `.gjc/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while GJC tracks G001/G002 story progress in the ledger. Ultragoal does not call `/goal clear`; before multiple sequential ultragoal runs in one session/thread, manually run `/goal clear` in the UI so the previous completed aggregate goal does not block or confuse the next `goal({"op":"create"})`.
+`ultragoal` turns a brief into repo-native artifacts and then drives a GJC goal safely through the unified `goal` tool. New plans default to a stable pointer-style aggregate GJC goal for the whole durable plan in `.gjc/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while GJC tracks G001/G002 story progress in the ledger. Ultragoal does not require any `/goal` slash-command between runs. For back-to-back ultragoal runs in one session/thread, call `goal({"op":"drop"})` only when `goal({"op":"get"})` still reports an active aggregate; then call `goal({"op":"create"})`. The goal tool stays armed across drop so the next create works in-session, and no slash-command cleanup exists or is required.
 
 - `.gjc/ultragoal/brief.md`
 - `.gjc/ultragoal/goals.json`
@@ -41,9 +41,12 @@ Use these exact goal-tool calls for the inline goal state:
 goal({"op":"get"})
 goal({"op":"create","objective":"<printed aggregate or per-story objective>"})
 goal({"op":"complete"})
+goal({"op":"drop"})
+goal({"op":"resume"})
 ```
+`drop` clears the active goal without exiting goal mode; `resume` reactivates a paused goal.
 
-The unified `goal` tool shares the same session goal state as `/goal`; use `goal({"op":"get"})` snapshots inside Ultragoal for ledger reconciliation.
+Use `goal({"op":"get"})` snapshots inside Ultragoal for ledger reconciliation. The unified `goal` tool is the only agent-facing surface for goal state; no `/goal` subcommand is required.
 
 ## Create goals
 
@@ -61,7 +64,7 @@ Loop until `gjc ultragoal status` reports all goals complete:
 1. Run `gjc ultragoal complete-goals`.
 2. Read the printed handoff.
 3. Call `goal({"op":"get"})`.
-4. If no active GJC goal exists, call `goal({"op":"create","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.
+4. If no active GJC goal exists, call `goal({"op":"create","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. If `goal({"op":"get"})` shows a stale dropped goal (status `"dropped"`) and a new aggregate must start, no extra cleanup is needed — `goal({"op":"create"})` succeeds directly. If a previous aggregate is still active and you genuinely need a fresh start in the same session, call `goal({"op":"drop"})` first, then `goal({"op":"create"})`.
 5. Complete the current GJC story only.
 6. Run a completion audit against the story objective and real artifacts/tests.
 7. Before any `--status complete` checkpoint, run the mandatory final cleanup/review gate below. In aggregate mode, do **not** call `goal({"op":"complete"})` for intermediate stories; checkpoint each story with a fresh `goal({"op":"get"})` snapshot whose aggregate objective is still `active`. On the final story, use the same fresh active snapshot to create the final aggregate receipt first; only after that receipt exists may `goal({"op":"complete"})` run.
@@ -192,11 +195,21 @@ Receipts are freshness-scoped:
 - 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.
 
+## Handoff back to planning
+
+When the aggregate ultragoal is complete OR the user requests return to planning/clarification, mark ultragoal ready for handoff so the skill tool's chain guard permits the backward transition:
+
+```
+gjc state ultragoal write --input '{"current_phase":"handoff"}' --json
+```
+
+The skill tool then dispatches `/skill:ralplan` or `/skill:deep-interview` same-turn and runs `gjc state ultragoal handoff --to <ralplan|deep-interview> --json` in-process to atomically demote ultragoal, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.
+
 ## Constraints
 
-- The shell command cannot directly invoke interactive `/goal`; it emits a model-facing handoff for the active GJC agent.
-- Ultragoal intentionally does not invoke `/goal clear` or hidden `thread/goal/clear`; use only the unified goal-tool surface: `goal({"op":"get"})`, `goal({"op":"create"})`, and `goal({"op":"complete"})`.
-- After a completed aggregate ultragoal run, clear the goal manually with `/goal clear` before starting another ultragoal run in the same session/thread.
+- The shell command emits a model-facing handoff for the active GJC agent; it does not invoke any `/goal` slash-command and the agent loop must not depend on any `/goal` subcommand.
+- Use only the unified goal-tool surface from the agent loop: `goal({"op":"get"})`, `goal({"op":"create"})`, `goal({"op":"complete"})`, `goal({"op":"drop"})`, `goal({"op":"resume"})`. `drop` clears the active goal without exiting goal mode so the next `goal({"op":"create"})` works in-session. No slash-command cleanup exists or is required; Ultragoal never calls any `/goal` subcommand.
+- For back-to-back ultragoal runs in the same session/thread, when `goal({"op":"get"})` still reports an active aggregate, call `goal({"op":"drop"})` before `goal({"op":"create"})`; when no active goal exists or the prior aggregate is already complete or dropped, call `goal({"op":"create"})` directly. The goal tool remains callable across drop; no slash-command cleanup exists or is required.
 - Never call `goal({"op":"create"})` when `goal({"op":"get"})` reports a different active goal.
 - Never call `goal({"op":"complete"})` unless the aggregate run or legacy per-story goal is actually complete.
 - In aggregate mode, intermediate and final story checkpoints require a matching `active` GJC goal snapshot; the final story checkpoint creates the final aggregate receipt before `goal({"op":"complete"})` may reconcile the inline goal state.