@gajae-code/coding-agent 0.18.6 → 0.18.8

package/src/defaults/gjc/extensions/grok-cli-vendor/src/provider/stream.ts

@@ -2,12 +2,18 @@ import type {
   Api,
   AssistantMessageEventStream,
   Context,
+  FetchImpl,
   Model,
   SimpleStreamOptions,
 } from '@gajae-code/ai/core';
 import { streamOpenAIResponses } from '@gajae-code/ai/providers/openai-responses';
+import {
+  getGrokCliVersion,
+  parseMinimumVersionFrom426,
+  updateVersionFromError,
+} from './version-manager';
 
-const GROK_CLI_VERSION = '0.2.33';
+type FetchInput = Parameters<FetchImpl>[0];
 
 /**
  * Stream function that adds Grok CLI-specific headers to requests.
@@ -16,6 +22,7 @@ const GROK_CLI_VERSION = '0.2.33';
  *   - x-grok-conv-id: <session/conversation ID>
  *   - x-grok-model-override: <model ID>
  *   - x-xai-token-auth: xai-grok-cli
+ *   - x-grok-client-version: learned from HTTP 426 responses; defaults to 1.0.13 and retries once on upgrade
  */
 export function streamGrokCli(
   model: Model<Api>,
@@ -23,10 +30,14 @@ export function streamGrokCli(
   options?: SimpleStreamOptions,
 ): AssistantMessageEventStream {
   const sessionId = options?.sessionId;
+
+  // Get the Grok CLI version: learned from 426 responses or fallback
+  const grokCliVersion = getGrokCliVersion();
+
   const headers: Record<string, string> = {
     ...options?.headers,
     'x-grok-client-identifier': 'gjc-grok-cli',
-    'x-grok-client-version': GROK_CLI_VERSION,
+    'x-grok-client-version': grokCliVersion,
     'x-xai-token-auth': 'xai-grok-cli',
     'x-grok-model-override': model.id,
   };
@@ -40,11 +51,63 @@ export function streamGrokCli(
     api: 'openai-responses',
   } as Model<'openai-responses'>;
 
+  // Wrap fetch to intercept 426 errors and extract version info
+  const baseFetch = options?.fetch ?? (globalThis.fetch.bind(globalThis) as FetchImpl);
+  const wrappedFetch = wrapFetchForVersionHandling(baseFetch);
+
   return streamOpenAIResponses(responsesModel, context, {
     ...options,
     headers,
-    onResponse(response) {
-      options?.onResponse?.(response, model);
+    fetch: wrappedFetch,
+    onResponse(response, _responseModel, scope, signal) {
+      return options?.onResponse?.(response, model, scope, signal);
     },
   });
 }
+
+/**
+ * Wraps a fetch function to learn from HTTP 426 responses and retry once with a newer version.
+ */
+function wrapFetchForVersionHandling(baseFetch: FetchImpl): FetchImpl {
+  return Object.assign(
+    async (input: FetchInput, init?: RequestInit): Promise<Response> => {
+      const firstInput =
+        input instanceof Request ? (input.clone() as unknown as FetchInput) : input;
+      const response = await baseFetch(firstInput, init);
+
+      if (response.status !== 426) return response;
+
+      let errorText: string;
+      try {
+        errorText = await response.clone().text();
+      } catch {
+        return response;
+      }
+
+      if (!parseMinimumVersionFrom426(errorText)) return response;
+
+      const retryHeaders = new Headers(
+        init?.headers ?? (input instanceof Request ? input.headers : undefined),
+      );
+      const requestedVersion = retryHeaders.get('x-grok-client-version');
+      const learnedVersion = updateVersionFromError(errorText);
+      if (!requestedVersion || learnedVersion === requestedVersion) return response;
+
+      retryHeaders.set('x-grok-client-version', learnedVersion);
+      const retryInput =
+        input instanceof Request ? (input.clone() as unknown as FetchInput) : input;
+      const retryResponse = await baseFetch(retryInput, { ...init, headers: retryHeaders });
+
+      if (retryResponse.status === 426) {
+        try {
+          updateVersionFromError(await retryResponse.clone().text());
+        } catch {
+          // Keep the retry response intact if its body cannot be inspected.
+        }
+      }
+
+      return retryResponse;
+    },
+    { preconnect: baseFetch.preconnect },
+  ) as FetchImpl;
+}

package/src/defaults/gjc/extensions/grok-cli-vendor/src/provider/version-manager.ts

@@ -0,0 +1,80 @@
+/**
+ * Grok CLI version manager with 426 error handling.
+ *
+ * Learns the minimum required Grok CLI version from xAI HTTP 426 "version outdated" responses.
+ * Falls back to a hardcoded version if no 426 has been received.
+ * Version updates are monotonic: learned versions never downgrade.
+ */
+
+const FALLBACK_VERSION = '1.0.13';
+
+// Minimum version xAI demanded in its latest HTTP 426 response.
+// A server-stated minimum never becomes less true, so it has no expiry.
+let learnedVersion: string | null = null;
+
+/**
+ * Get the current Grok CLI version: learned from 426 responses (never downgrades),
+ * otherwise the fallback version.
+ */
+export function getGrokCliVersion(): string {
+  return learnedVersion ?? FALLBACK_VERSION;
+}
+
+/**
+ * Parse a minimum version from an HTTP 426 error response body.
+ * Expected format: "Your Grok CLI version (X.Y.Z) is outdated. Please update to version A.B.C or later"
+ */
+export function parseMinimumVersionFrom426(errorBody: string): string | null {
+  const versionMatch = errorBody.match(/update to version (\d+\.\d+\.\d+) or later\b/i);
+  return versionMatch?.[1] ?? null;
+}
+
+/**
+ * Update the learned version from a 426 error response.
+ * Versions are monotonic: a learned version never downgrades.
+ * Returns the version to use for the next request.
+ */
+export function updateVersionFromError(errorBody: string): string {
+  const minVersion = parseMinimumVersionFrom426(errorBody);
+  if (!minVersion) {
+    return getGrokCliVersion();
+  }
+
+  // Compare against the active value so an older minimum cannot downgrade the fallback.
+  if (isVersionGreater(minVersion, getGrokCliVersion())) {
+    learnedVersion = minVersion;
+  }
+
+  return getGrokCliVersion();
+}
+
+/**
+ * Determine if version1 is greater than version2 (naive semver comparison).
+ * Prevents learned versions from downgrading due to out-of-order 426 responses.
+ */
+function isVersionGreater(version1: string, version2: string): boolean {
+  const parts1 = version1.split('.').map((x) => parseInt(x, 10) || 0);
+  const parts2 = version2.split('.').map((x) => parseInt(x, 10) || 0);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] ?? 0;
+    const p2 = parts2[i] ?? 0;
+    if (p1 > p2) return true;
+    if (p1 < p2) return false;
+  }
+  return false;
+}
+
+/**
+ * Reset the learned version (mainly for testing).
+ */
+export function resetVersionCache(): void {
+  learnedVersion = null;
+}
+
+/**
+ * Get the fallback version (mainly for testing).
+ */
+export function getFallbackVersion(): string {
+  return FALLBACK_VERSION;
+}

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

@@ -1,7 +1,7 @@
 ---
 name: deep-interview
 description: Socratic deep interview with mathematical ambiguity gating before explicit execution approval
-argument-hint: "[--trace] [--quick|--standard|--deep] <idea or vague description>"
+argument-hint: "[--crystallize --input <json-or-@file> --slug <slug>] [--trace] [--json] [--quick|--standard|--deep] <idea or vague description>"
 pipeline: [deep-interview, ralplan]
 handoff-policy: approval-required
 handoff: .gjc/_session-{sessionid}/specs/deep-interview-{slug}.md
@@ -74,6 +74,52 @@ source: "forked from upstream deep-interview skill and rebranded for GJC"
 - After 3 consecutive agent-resolved answers (accepted auto-answers), route the next question to the user (dialectic rhythm guard)
 - Run an independent closure audit and a one-sentence goal restatement, each requiring explicit user confirmation, before crystallizing the spec
 - When `--trace` is active, use the bounded trace evidence summary as pre-question context; never dump raw logs, raw files, or unbounded search output into questions, scoring, specs, or handoffs
+
+**Native kickoff contract.** Seed the interviewing phase with `gjc deep-interview [--trace] [--json] [--quick|--standard|--deep] <idea or vague description>`. `--trace` enables the bounded evidence pre-step and `--json` selects machine-readable output; neither flag changes the approval gate. The generic workflow API retains `api --input <json-or-@file>` for bounded payloads and does not authorize execution.
+
+**Native spec-write contract.** Persist a final specification with `gjc deep-interview --write --stage final --slug <slug> --spec <markdown-or-path> [--force] [--json]`. The `--force` option is limited to overwriting corrupt deep-interview state and never grants execution approval; use the separate approval transition before any execution handoff.
+
+### Crystallize sub-mode
+
+`--crystallize` is a bounded shortcut on this skill, not a new workflow or an execution path. It is the sanctioned `interviewing` → `handoff` transition for a ready Crystal and must remain non-authorizing. Use it only when the current conversation already contains material requirements and decisions. Before any state write, capture a deterministic conversation snapshot with an explicit message range, source revision, and digest. Extract each item into exactly one of `confirmed`, `inferred`, or `disputed`; every confirmed goal, constraint, decision, and acceptance criterion MUST retain a verbatim source anchor. Do not treat inferred or disputed text as confirmed.
+
+Submit the bounded snapshot and extraction through the native crystallize writer. The writer is the sole promoter into the existing deep-interview state/spec shape; exploration remains non-canonical. A sufficient snapshot creates a versioned Crystal/spec without replaying interview rounds. One or two blocking gaps may be asked through `ask`; unresolved consequential choices use the existing lateral/adversarial review hook. Broad ambiguity MUST fall back to the ordinary full interview flow. Never create a Crystal when the snapshot revision or digest is stale or mismatched.
+
+When a prior Crystal exists, compare only evidence after its bound revision. Preserve unchanged confirmed material and record a versioned delta: additive requirements create the next version, changed constraints or decisions reopen affected fields and invalidate execution approval, changed goals supersede the prior Crystal, and conflicting later evidence marks it stale rather than overwriting it. Every promoted Crystal records `spec_version`, source range/revision/digest, classifications, anchors, open gaps, and `execution_approval: not-approved` unless a separate existing approval gate later records approval. Crystallization MUST NOT invoke implementation, `run`, `ralplan`, or any automatic handoff.
+
+**Native CLI contract.** Invoke this sub-mode as `gjc deep-interview --crystallize --input <json-or-@file> --slug <slug> [--session-id <id>] [--json]`; both `--input` and `--slug` are required. The `--input` value is either inline JSON or an `@file` and is bounded to 1 MiB. It must have this required object shape (the listed arrays are optional when empty):
+
+```json
+{
+  "snapshot": {
+    "revision": 1,
+    "start": 0,
+    "end": 0,
+    "digest": "<64 lowercase hex SHA-256>",
+    "messages": [
+      { "index": 0, "role": "user", "content": "Build audit reports" }
+    ]
+  },
+  "current_revision": 1,
+  "items": [
+    {
+      "id": "goal:reports",
+      "kind": "goal",
+      "classification": "confirmed",
+      "statement": "Build audit reports",
+      "anchor": { "message_index": 0, "quote": "Build audit reports" }
+    }
+  ],
+  "open_gaps": [],
+  "conflicts": []
+}
+```
+
+`snapshot.messages` MUST be ordered, unique, contiguous, and cover every index from `start` through `end`; the range and message list are capped at 200 messages, `items` at 128 entries, and each text field at 10,000 characters. `snapshot.end` MUST be the live transcript tail, `current_revision` MUST equal `snapshot.revision`, and `digest` MUST be the SHA-256 digest of the normalized snapshot. For a prior Crystal, include every message after its stored boundary; never skip a range or reuse stale evidence. Items use exactly one of `goal`, `constraint`, `decision`, `acceptance_criterion`, or `non_goal` and exactly one of `confirmed`, `inferred`, or `disputed`; confirmed items require a verbatim user `anchor` and inferred/disputed items never count as confirmed requirements.
+
+For the first Crystal, `snapshot.start` MUST be 0 and the full authenticated transcript MUST fit within 200 messages (exactly 200 is valid). If it exceeds that bound, continue the ordinary interview flow; never submit only the last 200 messages or replace authenticated evidence with a summary. With a canonical stored prior Crystal preserving the prefix, a contiguous delta of at most 200 messages may start after its stored boundary even when the full transcript is longer than 200 messages.
+
+The ordinary state writer has a separate required shape: `gjc deep-interview write --input '{"state":{...}}'` and `stage --for <transition> --input '{"state":{...}}'`; stage transitions are incremental deltas, not whole-transcript replacements. A Crystal is ready only when ambiguity/readiness evidence has no unresolved gaps, conflicts, or disputed requirements; `needs-questions`, `stale`, and `superseded` results do not publish a spec and return to the ordinary interview/resolution path. A ready result persists the versioned artifact `.gjc/_session-{sessionid}/specs/deep-interview-{slug}-v{spec_version}.md`. Every Crystal starts with `execution_approval: not-approved`; only the separate `gjc deep-interview approve-execution --json` action records explicit user execution approval for a ready canonical Crystal, and handoff never grants that approval.
 </Execution_Policy>
 
 <Internal_Auto_Mode_Protocol>
@@ -669,7 +715,7 @@ When ambiguity ≤ threshold (or hard cap / early exit):
    - Apply the self-proofread once (DIPP-5) to newly generated spec prose before persistence, including generated natural-language table cells such as coverage notes, while preserving transcript answers, quoted/source text, code identifiers, file paths, commands, JSON/settings keys, table structure/fixed labels, and `.gjc/_session-{sessionid}/specs/deep-interview-{slug}.md` unchanged.
 2. **Write the final spec through the workflow CLI**: persist the artifact at `.gjc/_session-{sessionid}/specs/deep-interview-{slug}.md`
    - Always use this exact final spec path. Prefer passing the spec markdown **inline** as the `--spec` value; only when it is too large to pass inline, stage it as a file in a system temp directory (`os.tmpdir()`/`$TMPDIR`, `/tmp`, `/var/tmp`) outside the project tree and pass that path — never write scratch specs to the repo root, the project tree, or `.gjc/`.
-   - 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.
+   - Use the native deep-interview write command with `--write --stage final --slug {slug} --spec <markdown-or-path> [--force] [--json]` for artifact and state persistence; `--force` only permits recovery from corrupt deep-interview state and direct `.gjc/` file edits remain forbidden.
    - 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.
 
@@ -789,6 +835,27 @@ After the spec is written, mark it `pending approval` and present execution opti
 
 **Question:** "Your spec is ready (ambiguity: {score}%). How would you like to proceed?"
 
+The actual Phase 5 `ask` question MUST include `workflowGate: { stage: "deep-interview", kind: "execution" }`. Keep the recognized ultragoal option label so an explicit selection creates the user-origin pending approval record. Concrete `ask` input:
+
+```json
+{
+  "questions": [{
+    "id": "deep-interview-execution",
+    "question": "Your spec is ready (ambiguity: {score}%). How would you like to proceed?",
+    "workflowGate": { "stage": "deep-interview", "kind": "execution" },
+    "options": [
+      { "label": "Refine with ralplan consensus (Recommended — default for almost all specs)" },
+      { "label": "Execute with ultragoal (only when spec is already implementation-ready and really simple)" },
+      { "label": "Continue research with autoresearch (research continuation, not execution)" },
+      { "label": "Refine further" }
+    ],
+    "multi": false
+  }]
+}
+```
+
+This tagged question does not itself authorize or automatically start implementation. Only an explicit ultragoal selection may be consumed by the separate `gjc deep-interview approve-execution --json` action; require that action to succeed before invoking `/skill:ultragoal`. Research/refinement choices, custom responses, cancellation, timeout, and untagged asks do not grant execution approval.
+
 **Options:**
 
 1. **Refine with ralplan consensus (Recommended — default for almost all specs)**
@@ -798,7 +865,7 @@ After the spec is written, mark it `pending approval` and present execution opti
 
 2. **Execute with ultragoal (only when spec is already implementation-ready and really simple)**
    - Description: "Goal-tracked autonomous execution — drives the spec to completion with verification. Skip ralplan refinement only when the spec is concrete, low-risk, and trivially small."
-   - Action: Invoke `/skill:ultragoal` with the spec file path as context only after the user explicitly selects this execution option. The spec replaces ultragoal planning input. Recommend this only when the spec needs no further planning; otherwise route through ralplan refinement first.
+   - Action: Only after the user explicitly selects this execution option, record that distinct approval through `gjc deep-interview approve-execution --json`, then invoke `/skill:ultragoal` with the spec file path as context. The handoff itself never grants approval and rejects an unapproved Crystal. The spec replaces ultragoal planning input. Recommend this only when the spec needs no further planning; otherwise route through ralplan refinement first.
 
 3. **Continue research with autoresearch (research continuation, not execution)**
    - Description: "Feed the crystallized spec into an autoresearch mission to deepen research grounding before any implementation planning. This is not an execution path and implements nothing."
@@ -808,24 +875,23 @@ After the spec is written, mark it `pending approval` and present execution opti
    - Description: "Continue interviewing to improve clarity (current: {score}%)"
    - Action: Return to Phase 2 interview loop.
 
-**IMPORTANT:** On explicit execution selection, **MUST** use the chosen bundled GJC workflow skill entrypoint (`/skill:ralplan` or `/skill:ultragoal`) inside the agent session. `gjc ralplan` is a native CLI that accepts the documented skill flags and seeds local `.gjc/_session-{sessionid}/state` receipts; agent sessions should still drive the consensus loop through `/skill:ralplan`. Implementation handoff defaults to `/skill:ultragoal`. The autoresearch option is a research continuation only and never an execution path. 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`.
+**IMPORTANT:** On explicit execution selection, **MUST** use the chosen bundled GJC workflow skill entrypoint (`/skill:ralplan` or `/skill:ultragoal`) inside the agent session. Before an approved Crystal can enter `/skill:ultragoal`, persist the user's separate execution decision with `gjc deep-interview approve-execution --json`; never attach approval to the handoff command. `gjc ralplan` is a native CLI that accepts the documented skill flags and seeds local `.gjc/_session-{sessionid}/state` receipts; agent sessions should still drive the consensus loop through `/skill:ralplan`. Implementation handoff defaults to `/skill:ultragoal`. The autoresearch option is a research continuation only and never an execution path. 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` or `/skill:ultragoal`, the final spec must already be persisted through the native deep-interview write command (`gjc deep-interview --write --stage final …`). That command itself moves the workflow to the `handoff` phase, so no separate state write is needed for the skill tool's chain guard. Verify readiness with:
+Before invoking `/skill:ralplan` or `/skill:ultragoal`, the ready Crystal must already expose its canonical versioned `spec_path`. Crystallization itself publishes that artifact and moves the workflow to the `handoff` phase; never issue a second direct spec write after Crystal publication. Verify readiness and reuse the returned `spec_path` with:
 
 ```
 gjc deep-interview read --json
 ```
 
-For a preselected deliberate ralplan path, prefer the single sanctioned bridge command instead:
+For a selected ralplan refinement path, hand off the already-published Crystal state without rewriting its spec:
 
 ```
-gjc \
-deep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json
+gjc state handoff --mode deep-interview --to ralplan --json
 ```
 
-That command persists `.gjc/_session-{sessionid}/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.
+Pass the canonical `spec_path` from `gjc deep-interview read --json` into `/skill:ralplan`. The state handoff is non-executing and does not grant execution approval. `/skill:ultragoal` still requires the separate `approve-execution` transition before its handoff.
 
 ### Approval-Gated Refinement Path (Recommended)
 
@@ -870,6 +936,31 @@ Skipping any stage is possible but reduces quality assurance:
 </Tool_Usage>
 
 <Examples>
+<Good>
+Kickoff with bounded trace evidence and machine-readable output:
+```
+gjc deep-interview --trace --standard "<idea>" --json
+```
+</Good>
+
+<Good>
+Final spec persistence with explicit corrupt-state recovery override:
+```
+gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --force --json
+```
+</Good>
+
+<Good>
+Bounded crystallization with an explicit slug and authenticated snapshot:
+```
+gjc deep-interview --crystallize --input '{"snapshot":{"revision":1,"start":0,"end":0,"digest":"<64 lowercase hex SHA-256>","messages":[{"index":0,"role":"user","content":"Build audit reports"}]},"current_revision":1,"items":[{"id":"goal:reports","kind":"goal","classification":"confirmed","statement":"Build audit reports","anchor":{"message_index":0,"quote":"Build audit reports"}}],"open_gaps":[],"conflicts":[]}' --slug audit-reports --json
+```
+The input is bounded and must cover the declared snapshot range exactly. A successful `ready`
+result writes `deep-interview-audit-reports-v1.md` (or the next `spec_version`), while unresolved
+gaps/conflicts remain non-ready and do not publish a spec. Execution still requires the separate
+`gjc deep-interview approve-execution --json` action after the user chooses an execution path.
+</Good>
+
 <Good>
 Targeting weakest dimension:
 ```
@@ -973,8 +1064,12 @@ Why bad: 45% ambiguity means nearly half the requirements are unclear. The mathe
 - [ ] Free-text answers passed the Refine gate; dialectic rhythm guard forced a user question after 3 agent-resolved answers; any auto-answer threshold crossing explicitly confirmed
 - [ ] Closure / Acceptance Guard and the one-sentence Restate gate both passed before crystallization
 - [ ] Interview reached ambiguity ≤ threshold OR an explicit early exit with warning
+- [ ] Kickoff flags matched the native contract: `--trace` and `--json` remained optional, bounded, and non-authorizing
 - [ ] Ordinary answered rounds auto-continued to the next weakest-dimension question with no generic continue/cancel/clear ask; any stop matched a legitimate terminal condition (threshold + closure gates, explicit user exit, invocation/resume suitability, or bounded safety recovery)
-- [ ] Spec persisted to `.gjc/_session-{sessionid}/specs/deep-interview-{slug}.md` exactly via the GJC CLI (no direct `.gjc/` edits without force override), covering every active topology component plus goal/constraints/acceptance criteria/clarity/ontology/transcript
+- [ ] Spec persisted to `.gjc/_session-{sessionid}/specs/deep-interview-{slug}.md` exactly via the GJC CLI (use `--force` only for corrupt-state recovery; no direct `.gjc/` edits), covering every active topology component plus goal/constraints/acceptance criteria/clarity/ontology/transcript
+- [ ] `--crystallize` received required `--input <json-or-@file>` and `--slug <slug>`; its snapshot is bounded, contiguous, digest-bound, and matched to the live transcript revision
+- [ ] A ready Crystal persisted the versioned `.gjc/_session-{sessionid}/specs/deep-interview-{slug}-v{spec_version}.md` artifact; `needs-questions`, `stale`, and `superseded` results did not publish a spec
+- [ ] Every Crystal recorded `execution_approval: not-approved`; only a separate explicit `gjc deep-interview approve-execution --json` transition can authorize execution, never crystallization or handoff
 - [ ] Spec metadata includes the auto/lateral counters (`auto_answered_rounds`, `lateral_reviews`, `refined_rounds`, `architect_failures`, `lateral_panel_failures`)
 - [ ] Execution bridge presented via `ask`; execution invoked only after explicit approval through a public workflow entrypoint (never direct implementation); state cleaned up after handoff
 </Final_Checklist>

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

@@ -33,9 +33,9 @@ For corrupt, tampered, unreadable, or stale current-session ralplan state, run `
 
 ## Planning/Execution Boundary
 
-Ralplan is planning only. It may inspect context and draft plan/spec/proposal artifacts, but those remain `pending approval` until explicit current-turn or structured-UI execution approval, or a valid non-off final receipt's runtime-owned `auto_handoff.effectiveTarget` admits the existing handoff chain. Before either admission, do not mutate product source, run mutation-oriented shell, commit, push, open PRs, invoke execution skills, or delegate implementation.
+Ralplan is planning only. It may inspect context and draft plan/spec/proposal artifacts, but those remain `pending approval` until tagged structured-UI execution approval for the current final artifact, or a valid non-off final receipt's runtime-owned `auto_handoff.effectiveTarget` admits the existing handoff chain. Before either admission, do not mutate product source, run mutation-oriented shell, commit, push, open PRs, invoke execution skills, or delegate implementation.
 
-Except for a terminal `planning_stuck` final receipt, explicitly naming `ultragoal` (including `/skill:` and `gjc` forms) counts as opting into execution for that skill — do not re-ask for the same consent.
+Explicitly naming `ultragoal` (including `/skill:` and `gjc` forms) selects the desired execution target; it does not replace structured approval for the current final artifact when `auto_handoff.effectiveTarget` is `off`. Never invent a direct approval record or infer execution consent from the skill name.
 
 Persist planning artifacts and handoffs through the ralplan CLI writer, never direct `.gjc/` edits:
 Direct `write`, `edit`, or `ast_edit` calls against `.gjc/_session-{sessionid}/specs`, `.gjc/_session-{sessionid}/plans`, `.gjc/_session-{sessionid}/state`, or any other `.gjc/` path are forbidden unless an explicit force override is active.
@@ -107,12 +107,14 @@ The consensus workflow:
       - For every confirmed open item, embed the resolved outcome into the final plan under an **## Intent Reconciliation** section so the `pending approval` artifact records each decision; record any item the user explicitly defers as an open confirmation under that same section.
    d. Persist the reconciliation with `gjc ralplan --write --worktree-root <repository_binding.worktreeRoot> --stage post-interview --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json`, then return the receipt/path plus a compact status (reconciled-clean / reconciled-with-revision / open-confirmations-pending) instead of pasting the full body.
 7. On reconciliation completion, re-check the review join gate (Critic `OKAY` plus Architect `CLEAR`/`APPROVE` for the same Planner artifact/pass), mark the plan `pending approval` unless execution is already authorized by the resolved handoff admission, then persist the ADR/final plan via `gjc ralplan --write --worktree-root <repository_binding.worktreeRoot> --stage final --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json`. Read the successful receipt's `auto_handoff` object; its ledger-backed `effectiveTarget` is runtime-owned and is the only automatic-routing decision; do not directly edit `.gjc/_session-{sessionid}/plans`. Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups) and, when present, the **## Intent Reconciliation** section.
-8. **Final admission and approval gate:** Reconciliation must first reach the successful final receipt from step 7. If that receipt has `auto_handoff.degradationReason: "planning_stuck"`, it is terminal: retain the `pending approval` artifact and **never dispatch**, including for an explicitly named execution skill; do not issue an approval `ask`. Otherwise, if its runtime-owned `auto_handoff.effectiveTarget` is `ultragoal`, that valid non-off receipt is explicit operator admission for same-turn execution through that target; proceed to step 9 without an `ask`. If it is `off`, including ordinary `off`, preserve the ordinary approval flow: if the user already explicitly named an execution skill in the current turn or via the structured approval UI (`ultragoal`, `/skill:ultragoal`, `gjc ultragoal`, or "Approve execution via ultragoal"), that is execution approval — skip the re-ask and proceed to step 9 with that skill. Otherwise, present the finalized plan via the `ask` tool (regardless of `--interactive`) with `workflowGate: { stage: "ralplan", kind: "approval" }` on the final question so RPC/headless clients receive a `ralplan`/`approval` workflow gate, not a deep-interview question gate. Use these options:
+8. **Final admission and approval gate:** Reconciliation must first reach the successful final receipt from step 7. If that receipt has `auto_handoff.degradationReason: "planning_stuck"`, it is terminal: retain the `pending approval` artifact and **never dispatch**, including for an explicitly named execution skill; do not issue an approval `ask`. Otherwise, if its runtime-owned `auto_handoff.effectiveTarget` is `ultragoal`, that valid non-off receipt is explicit operator admission for same-turn execution through that target; proceed to step 9 without an `ask`. If it is `off`, including ordinary `off`, require an accepted tagged structured approval for the current final artifact even if the user already named an execution skill. Unless that current final artifact already has that approval, present the finalized plan via the `ask` tool (regardless of `--interactive`) with `workflowGate: { stage: "ralplan", kind: "approval" }` on the final question so RPC/headless clients receive a `ralplan`/`approval` workflow gate, not a deep-interview question gate. Identify the current final receipt/path in the question. A revised final artifact requires a fresh structured approval; approval of a previous final artifact does not carry over. Use these options:
    - **Refine further** — re-run the consensus loop / request changes, then return here
    - **Approve execution via ultragoal (Recommended)** — goal-tracked autonomous execution
    - **Stop here** — keep the plan as `pending approval` and make no further changes
 
    Always include a free-text option for the ordinary `off` approval flow. Do not stop with plain text and no `ask` in that flow; its terminal action is this `ask`.
+
+   Example: a request to "plan this, then use `/skill:ultragoal`" still requires the tagged final approval `ask` after step 7 when the receipt resolves to `off`. Only an accepted **Approve execution via ultragoal** choice for that current final artifact admits step 9. Free text, refinement, cancellation, timeout, and **Stop here** do not authorize execution.
 9. On valid automatic admission or explicit approval, invoke the admitted/approved `/skill:ultragoal` target by default. On **Refine further**, return to the step 5 re-review loop. On **Stop here**, leave the `pending approval` artifact and stop. A `planning_stuck` final receipt never reaches this step. Never implement directly.
 
    Before invoking `/skill:ultragoal`, mark ralplan ready for handoff so the skill tool's chain guard permits the transition:
@@ -221,4 +223,4 @@ Gate auto-pass signals: file path, issue/PR number, camelCase/PascalCase/snake_c
 On consensus approval, choose:
 - **ultragoal**: goal-tracked autonomous execution with verification (recommended default)
 
-A redirected request proceeds only through the structured approval option or an explicit execution-skill choice; `just do it` / `skip planning` alone leaves the plan `pending approval`.
+A redirected request proceeds only through the tagged structured approval for the current final artifact or a valid non-off final receipt's automatic admission; naming an execution skill or saying `just do it` / `skip planning` alone leaves the plan `pending approval`.

package/src/defaults/gjc-defaults.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { BundledDefaultContentError, readBundledContentSync } from "./gjc-defaults";
-import type { BundledGjcSkillCatalogEntry } from "./gjc-skills.generated";
+import { BUNDLED_GJC_SKILL_CATALOG, type BundledGjcSkillCatalogEntry } from "./gjc-skills.generated";
 
 describe("bundled default content", () => {
 	test("unreadable source throws a typed contextual error", () => {
@@ -20,4 +20,21 @@ describe("bundled default content", () => {
 			expect((error as Error).message).toContain("Unable to read bundled GJC definition");
 		}
 	});
+
+	test("every catalog entry carries an embedded source path that matches its lazy import", async () => {
+		for (const entry of BUNDLED_GJC_SKILL_CATALOG) {
+			expect(entry.sourcePath, entry.relativePath).toBeString();
+			expect(readBundledContentSync(entry)).toBe(await entry.loadContent());
+		}
+	});
+
+	test("sync reads use the embedded source path, not import.meta.dir (compiled binaries, #6421)", () => {
+		const autoresearch = BUNDLED_GJC_SKILL_CATALOG.find(entry => entry.name === "autoresearch")!;
+		const entry = {
+			...autoresearch,
+			relativePath: "skills/not-laid-out-under-import-meta-dir/SKILL.md",
+		} as BundledGjcSkillCatalogEntry;
+
+		expect(readBundledContentSync(entry)).toContain("name: autoresearch");
+	});
 });

package/src/defaults/gjc-defaults.ts

@@ -104,6 +104,9 @@ export interface DefaultGjcDefinitionInstallResult {
 	retired: RetiredGjcDefinitionFile[];
 }
 function sourcePathForBundledEntry(entry: BundledGjcSkillCatalogEntry): string {
+	// Prefer the embedded asset path: `import.meta.dir` is `/$bunfs/root` in a
+	// compiled binary, where the `gjc/` tree is not laid out as files.
+	if (entry.sourcePath) return entry.sourcePath;
 	const relative = entry.kind === "skill" ? entry.relativePath : entry.relativePath.replace(/^skill-fragments\//, "");
 	return entry.kind === "skill"
 		? path.join(import.meta.dir, "gjc", relative)