@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/customization/types.ts

@@ -0,0 +1,223 @@
+/**
+ * Core types and scope resolution for the `/extensions` umbrella local
+ * customization surface (issue #4291, parent #4283).
+ *
+ * `.gjc` is the canonical persisted authority at two scopes:
+ * - project-local: `<project>/.gjc/`
+ * - user-global:   `~/.gjc/agent/`
+ *
+ * Claude Code and Codex layouts are import sources only — never a parallel
+ * runtime authority. This module defines the narrow contract types the UI
+ * and import flow consume without coupling to sibling ownership internals
+ * or to the provider/extension-module ExtensionDashboard.
+ */
+import * as path from "node:path";
+import { getAgentDir, getMCPConfigPath, getProjectAgentDir } from "@gajae-code/utils";
+import type { MigrateSource } from "../migrate/types";
+import type { MCPServerConfig } from "../runtime-mcp/types";
+
+// ---------------------------------------------------------------------------
+// Scope
+// ---------------------------------------------------------------------------
+
+export type GjcScope = "project" | "global";
+
+export interface GjcScopePaths {
+	scope: GjcScope;
+	/** Root directory: `<project>/.gjc` or `~/.gjc/agent` */
+	root: string;
+	/** MCP config: `<root>/mcp.json` */
+	mcpConfigPath: string;
+	/** Skills directory: `<root>/skills/` */
+	skillsDir: string;
+	/** Hooks directory: `<root>/hooks/` */
+	hooksDir: string;
+}
+
+export function resolveScopePaths(scope: GjcScope, projectCwd: string): GjcScopePaths {
+	if (scope === "project") {
+		const root = getProjectAgentDir(projectCwd);
+		return {
+			scope,
+			root,
+			mcpConfigPath: getMCPConfigPath("project", projectCwd),
+			skillsDir: path.join(root, "skills"),
+			hooksDir: path.join(root, "hooks"),
+		};
+	}
+	const root = getAgentDir();
+	return {
+		scope,
+		root,
+		mcpConfigPath: getMCPConfigPath("user", projectCwd),
+		skillsDir: path.join(root, "skills"),
+		hooksDir: path.join(root, "hooks"),
+	};
+}
+
+export function scopeLabel(scope: GjcScope): string {
+	return scope === "project" ? "Project .gjc" : "Global .gjc";
+}
+
+// ---------------------------------------------------------------------------
+// Customization surfaces
+// ---------------------------------------------------------------------------
+
+export type CustomizationSurface = "skills" | "hooks" | "mcps";
+
+export const CUSTOMIZATION_SURFACES: readonly CustomizationSurface[] = ["skills", "hooks", "mcps"];
+
+export function surfaceLabel(surface: CustomizationSurface): string {
+	switch (surface) {
+		case "skills":
+			return "Skills";
+		case "hooks":
+			return "Hooks";
+		case "mcps":
+			return "MCPs";
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Import source
+// ---------------------------------------------------------------------------
+
+export type ImportProduct = Exclude<MigrateSource, "opencode">;
+export type ImportSourceScope = "project" | "user";
+
+export const IMPORT_PRODUCTS: readonly ImportProduct[] = ["claude-code", "codex"];
+export const IMPORT_SOURCE_SCOPES: readonly ImportSourceScope[] = ["project", "user"];
+
+export function productLabel(product: ImportProduct): string {
+	switch (product) {
+		case "claude-code":
+			return "Claude Code";
+		case "codex":
+			return "Codex";
+	}
+}
+
+export function sourceScopeLabel(scope: ImportSourceScope): string {
+	return scope === "project" ? "Project-local" : "User-global";
+}
+
+export function sourceConfigDir(
+	product: ImportProduct,
+	sourceScope: ImportSourceScope,
+	projectCwd: string,
+	homeDir: string,
+): string {
+	if (product === "claude-code") {
+		return sourceScope === "project" ? path.join(projectCwd, ".claude") : path.join(homeDir, ".claude");
+	}
+	return sourceScope === "project" ? path.join(projectCwd, ".codex") : path.join(homeDir, ".codex");
+}
+
+// ---------------------------------------------------------------------------
+// Inventory row — provenance/status model for the dashboard
+// ---------------------------------------------------------------------------
+
+export type InventoryStatus =
+	| "enabled"
+	| "disabled"
+	| "invalid"
+	| "shadowed"
+	| "quarantined"
+	| "imported"
+	| "restart-required";
+
+export interface InventoryRow {
+	/** Stable row identity: `<surface>:<scope>:<path>` */
+	id: string;
+	/** Surface kind */
+	surface: CustomizationSurface;
+	/** Entry name */
+	name: string;
+	/** Display name */
+	displayName: string;
+	/** Effective status */
+	status: InventoryStatus;
+	/** Provenance — which scope/convention discovered it */
+	provenance: string;
+	/** Absolute discovered path — the exact identity mutations act on */
+	path: string;
+	/** Scope that persists this row (project `.gjc` or global `.gjc`) */
+	scope: GjcScope;
+	/** Short description (no secrets) */
+	description?: string;
+	/** Diagnostics/remediation detail for invalid/conflicted rows */
+	diagnostics?: string[];
+	/** Redacted inspector payload (never contains secret values) */
+	raw: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Normalized import preview
+// ---------------------------------------------------------------------------
+
+export type ImportCollisionPolicy = "skip" | "rename" | "overwrite";
+
+export type ImportEntryStatus = "add" | "conflict" | "unsupported" | "redacted" | "overwrite";
+
+export interface ImportPreviewEntry {
+	surface: CustomizationSurface;
+	/** Source name in the foreign layout */
+	sourceName: string;
+	/** Destination name in `.gjc` (may differ under rename policy) */
+	destinationName: string;
+	status: ImportEntryStatus;
+	/** Source path category (file, section, etc.) */
+	sourceCategory: string;
+	/** Redacted description for the preview UI */
+	description: string;
+	/** Reason for conflict/unsupported/redaction if applicable */
+	reason?: string;
+}
+
+export interface NormalizedPayload {
+	mcp?: { name: string; config: MCPServerConfig };
+	skill?: { slug: string; content: string };
+	hook?: { phase: "pre" | "post"; fileName: string; content: string };
+}
+
+export interface ImportPreview {
+	product: ImportProduct;
+	sourceScope: ImportSourceScope;
+	destinationScope: GjcScope;
+	surfaces: CustomizationSurface[];
+	entries: ImportPreviewEntry[];
+	/** Aggregate warnings across all entries */
+	warnings: string[];
+}
+
+/**
+ * Validated apply plan produced alongside the redacted preview. `payloads` is
+ * parallel to `preview.entries` (undefined for entries that carry no write).
+ * It is deliberately separate from the preview DTO: the preview is safe to
+ * serialize and display, while the plan holds full file contents and MCP
+ * secret values and is only consumed by the apply transaction.
+ */
+export interface ImportPlan {
+	preview: ImportPreview;
+	payloads: readonly (NormalizedPayload | undefined)[];
+}
+
+// ---------------------------------------------------------------------------
+// Import result
+// ---------------------------------------------------------------------------
+
+export type ImportOutcome = "imported" | "skipped" | "renamed" | "overwritten" | "failed";
+
+export interface ImportResultEntry {
+	surface: CustomizationSurface;
+	sourceName: string;
+	destinationName: string;
+	outcome: ImportOutcome;
+	reason?: string;
+}
+
+export interface ImportResult {
+	entries: ImportResultEntry[];
+	/** True if all entries succeeded (imported/skipped/renamed/overwritten) */
+	ok: boolean;
+}

package/src/daemon/control-types.ts

@@ -8,7 +8,8 @@
 
 export type DaemonKind = "telegram" | "discord" | "slack";
 
-export type DaemonAction = "list" | "status" | "stop" | "reload";
+/** `reload` remains the controller result verb; `restart` is the CLI canonical action. */
+export type DaemonAction = "list" | "status" | "stop" | "restart" | "reload";
 
 export type DaemonHealth = "not_configured" | "stopped" | "running" | "stale" | "stopping" | "error";
 
@@ -45,6 +46,12 @@ export interface DaemonOperationOptions {
 	force?: boolean;
 	/** For reload: spawn a fresh owner even when none is currently running. */
 	spawnIfStopped?: boolean;
+	/**
+	 * A post-update recovery has already force-stopped every selected daemon.
+	 * When global delivery is disabled, acknowledge its canonical restart stage
+	 * without spawning a transport that would resume delivery.
+	 */
+	allowDisabledNoop?: boolean;
 }
 
 export interface DaemonRecovery {

package/src/daemon/operator-contract.ts

@@ -3,7 +3,7 @@
  *
  * One source of truth for the beginner-safe operational vocabulary so the
  * guided human surface and the machine-readable JSON never drift:
- * - the terse action verbs plus operator aliases (e.g. `restart` -> `reload`),
+ * - the terse action verbs plus the retired `reload` operator alias,
  * - process exit codes,
  * - concise vs. `--verbose` human rendering of statuses and results, and
  * - actionable recovery guidance for a token/chat ownership mismatch.
@@ -15,15 +15,15 @@
 import type { DaemonAction, DaemonOperationResult, DaemonRecovery, DaemonStatus } from "./control-types";
 
 /** Canonical daemon actions accepted as the leading verb. */
-export const DAEMON_CANONICAL_ACTIONS: readonly DaemonAction[] = ["list", "status", "stop", "reload"];
+export const DAEMON_CANONICAL_ACTIONS: readonly DaemonAction[] = ["list", "status", "stop", "restart"];
 
 /**
- * Operator-friendly aliases resolved to a canonical action. `restart` is the
- * routine "reload if running, otherwise start" verb; it maps onto `reload`,
- * whose default already spawns a fresh owner when none is running.
+ * `restart` is the routine "reload if running, otherwise start" verb. Keep
+ * `reload` only as an input compatibility token; internal callers must use
+ * the canonical restart action.
  */
 export const DAEMON_ACTION_ALIASES: Readonly<Record<string, DaemonAction>> = {
-	restart: "reload",
+	reload: "restart",
 };
 
 /** Every token accepted in the leading action position (canonical + aliases). */

package/src/defaults/gjc/extensions/grok-cli-vendor/src/models/catalog.ts

@@ -9,6 +9,7 @@ const COST_BUILD = { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0.2 };
 const COST_COMPOSER_FAST = { input: 3, output: 15, cacheRead: 0.5, cacheWrite: 0 };
 const COST_43 = { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 };
 const COST_45 = { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 };
+const COST_46 = { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 };
 const COST_420 = { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 };
 
 // ─── Model type ───────────────────────────────────────────────────────────────
@@ -73,6 +74,18 @@ const FALLBACK_MODELS: GrokCliModelConfig[] = [
     contextWindow: 1_000_000,
     maxTokens: 30_000,
   },
+  {
+    // Official metadata and pricing: https://docs.x.ai/developers/models/grok-4.6
+    id: 'grok-4.6',
+    name: 'Grok 4.6',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: COST_46,
+    contextWindow: 500_000,
+    maxTokens: 30_000,
+    // https://docs.x.ai/developers/model-capabilities/text/reasoning: xhigh is 4.6 and later.
+    maxReasoningEffort: Effort.XHigh,
+  },
   {
     // Official metadata and pricing: https://docs.x.ai/developers/models/grok-4.5
     id: 'grok-4.5',
@@ -122,8 +135,9 @@ const FALLBACK_MODELS: GrokCliModelConfig[] = [
   },
 ];
 
-// Official aliases: https://docs.x.ai/developers/models/grok-4.5
+// Official aliases: https://docs.x.ai/developers/models/grok-4.6
 const MODEL_ALIASES: Readonly<Record<string, string>> = {
+  'grok-4.6-latest': 'grok-4.6',
   'grok-4.5-latest': 'grok-4.5',
   'grok-build-latest': 'grok-4.5',
 };
@@ -138,18 +152,29 @@ function getCanonicalModelName(modelId: string): string {
   return MODEL_ALIASES[name] ?? name;
 }
 
+function matchesModelFamily(name: string, modelId: string): boolean {
+  if (name === modelId) return true;
+  const suffix = name.slice(modelId.length + 1);
+  return name.startsWith(`${modelId}-`) && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(suffix);
+}
+
 export function getMaxReasoningEffort(modelId: string): Effort | undefined {
   const name = getCanonicalModelName(modelId);
-  return FALLBACK_MODELS.find(
-    (model) => name === model.id.toLowerCase() || name.startsWith(`${model.id.toLowerCase()}-`),
-  )?.maxReasoningEffort;
+  return FALLBACK_MODELS.find((model) => matchesModelFamily(name, model.id.toLowerCase()))
+    ?.maxReasoningEffort;
 }
 
-const EFFORT_CAPABLE_PREFIXES = ['grok-3-mini', 'grok-4.20-multi-agent', 'grok-4.3', 'grok-4.5'];
+const EFFORT_CAPABLE_PREFIXES = [
+  'grok-3-mini',
+  'grok-4.20-multi-agent',
+  'grok-4.3',
+  'grok-4.5',
+  'grok-4.6',
+];
 
 export function supportsReasoningEffort(modelId: string): boolean {
   const name = getCanonicalModelName(modelId);
-  if (!EFFORT_CAPABLE_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+  if (!EFFORT_CAPABLE_PREFIXES.some((prefix) => matchesModelFamily(name, prefix))) {
     return false;
   }
   const model = resolveModels().find((entry) => getCanonicalModelName(entry.id) === name);

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

@@ -104,14 +104,14 @@ Complete this phase before Phase 1, before brownfield exploration, before GJC st
 1. **Prefer pre-resolved native state**:
    - First inspect active deep-interview state with `gjc deep-interview read --json`.
    - If state contains a finite numeric `threshold` and a non-empty `threshold_source`, use those values, set `<resolvedThreshold>`, `<resolvedThresholdPercent>`, and `<resolvedThresholdSource>`, and skip optional settings-file reads. This is the normal `/skill:deep-interview` path because the native hook already resolved settings quietly before loading the skill.
-2. **Only if native state lacks a resolved threshold, read threshold settings in runtime precedence order**:
-   - YAML config first: read the **single** modern config path the environment selects — `$GJC_CODING_AGENT_DIR/config.yml` when `GJC_CODING_AGENT_DIR` is set, else `$GJC_CONFIG_DIR/agent/config.yml` when `GJC_CONFIG_DIR` is set, else `~/.gjc/agent/config.yml`. Do not cascade through the other YAML locations when the selected one is absent or invalid.
-   - Then JSON settings: project settings `./.gjc/settings.json`, then user settings `[$GJC_CONFIG_DIR|~/.gjc]/settings.json`.
-   - Read `gjc.deepInterview.ambiguityThreshold` only from files that are known to exist; optional config/settings-file absence is expected and must not be surfaced as failed `Read` calls.
-   - Do not probe arbitrary ancestor candidates such as `../../.gjc/settings.json`; use the current project `.gjc/settings.json` and user settings only.
+2. **Only if native state lacks a resolved threshold, read threshold settings in the runtime precedence order** (one shared resolver; first valid value wins):
+   1. project `.gjc/config.yml`
+   2. user `<agentDir>/config.yml` (normally `~/.gjc/agent/config.yml`, honoring `GJC_CODING_AGENT_DIR`/`PI_CODING_AGENT_DIR`; XDG variables apply only to categorized data/state/cache subdirectories, never to the workflow config path)
+   3. built-in default (`0.05` before resolution-flag fallback)
+   - `config.yml` uses the nested (schema) form - `gjc: { deepInterview: { ambiguityThreshold } }`. Project configuration beats user configuration. The reported `threshold_source` is the canonical path of the winning file, or the default. `config.yml` is the ONLY settings surface: the legacy `settings.json` files' workflow keys are retired: the config-root `~/.gjc/settings.json` is migrated once into the default global agent `config.yml` and its source removed, while the project `.gjc/settings.json` is retained for non-workflow settings (only its workflow keys are migrated into project `.gjc/config.yml` and no longer read unless a migration target is absent - a migration that could not publish (e.g. a read-only `.gjc`) leaves the retained legacy value effective as the previously configured override until it can publish). Invalid optional settings files continue to the next layer or the default (tolerant) — never a failed `Read`; do not probe arbitrary ancestor candidates.
 3. **Resolve threshold and source**:
    - Use the first valid configured value in the precedence order above; otherwise use the mode default when a resolution flag was passed: `--quick` = `0.6`, `--standard` = `0.5`, `--deep` = `0.35`; with no resolution flag, use the base default `0.05`.
-   - Set these run variables exactly: `<resolvedThreshold>`, `<resolvedThresholdPercent>`, and `<resolvedThresholdSource>` (for example `GJC_CODING_AGENT_DIR/config.yml`, `$GJC_CONFIG_DIR/agent/config.yml`, `~/.gjc/agent/config.yml`, `./.gjc/settings.json`, `[$GJC_CONFIG_DIR|~/.gjc]/settings.json`, or the selected mode default).
+   - Set these run variables exactly: `<resolvedThreshold>`, `<resolvedThresholdPercent>`, and `<resolvedThresholdSource>` (for example `./.gjc/config.yml`, `<agentDir>/config.yml` such as `~/.gjc/agent/config.yml`, or the selected mode default).
 4. **Emit the required first line to the user before any other interview announcement**:
 
 ```
@@ -984,23 +984,12 @@ Why bad: 45% ambiguity means nearly half the requirements are unclear. The mathe
 <Advanced>
 ## Configuration
 
-Optional settings in `.gjc/settings.json`:
+Optional settings in `.gjc/config.yml`:
 
-```json
-{
-  "gjc": {
-    "deepInterview": {
-      "ambiguityThreshold": <resolvedThreshold>,
-      "maxRounds": 100,
-      "softWarningRounds": 16,
-      "minRoundsBeforeExit": 3,
-      "enableChallengeAgents": true,
-      "autoExecuteOnComplete": false,
-      "defaultExecutionMode": null,
-      "scoringModel": "opus"
-    }
-  }
-}
+```yaml
+gjc:
+  deepInterview:
+    ambiguityThreshold: 0.7
 ```
 
 ## Resume

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

@@ -91,7 +91,7 @@ The consensus workflow:
    e. Re-join Architect and Critic verdicts for the same revised Planner artifact/pass (including a fresh disposition stage if new conflicts appear)
    f. Repeat this loop until Critic returns `OKAY` **and** Architect is `CLEAR`/`APPROVE` for the same Planner artifact/pass, or 5 iterations are reached
    g. If 5 iterations are reached without Critic `OKAY` plus Architect `CLEAR`/`APPROVE`, **stop opening further planner/revision passes**. Preserve the best version as a terminal `PLANNING-STUCK` result; do not route it to automatic or explicit execution.
-   h. **Runtime budget (#3165):** native `gjc ralplan --write` refuses a new `planner`/`revision` that would open consensus iteration **> max** (default **5**, overridable via `gjc.ralplan.maxIterations` in project/user `.gjc/settings.json`, integer 1..20). Cap uses the same iteration definition as the HUD (`planner`/`revision` openers in `index.jsonl`). Overflow exits **3**, prints operator-visible **`PLANNING-STUCK`** on stdout (and stderr detail; JSON includes `planning_stuck: true`), and still allows `architect`/`critic` within an already-opened pass plus `post-interview`/`adr`/`final` so the best plan can be escalated to `pending approval` without dispatch. A new `--run-id` starts a fresh budget.
+   h. **Runtime budget (#3165):** native `gjc ralplan --write` refuses a new `planner`/`revision` that would open consensus iteration **> max** (default **5**, overridable via `gjc.ralplan.maxIterations`, integer 1..20, using the workflow-settings precedence below). Cap uses the same iteration definition as the HUD (`planner`/`revision` openers in `index.jsonl`). Overflow exits **3**, prints operator-visible **`PLANNING-STUCK`** on stdout (and stderr detail; JSON includes `planning_stuck: true`), and still allows `architect`/`critic` within an already-opened pass plus `post-interview`/`adr`/`final` so the best plan can be escalated to `pending approval` without dispatch. A new `--run-id` starts a fresh budget.
 6. **Post-ralplan interview** (intent reconciliation gate): After the review join gate has both Critic `OKAY` and Architect `CLEAR`/`APPROVE` for the same Planner artifact/pass, and before the plan is finalized, reconcile the consensus plan against the user's actual intent. The goal is to make sure ralplan did not silently bake in assumptions that conflict with what the user wants.
    a. **Collect open items** from the run: every assumption the Planner/Architect/Critic resolved by assumption rather than by stated fact, every ambiguity flagged during review, and every decision the loop made without explicit user input. Source these from the persisted `planner`/`architect`/`critic`/`revision` stage artifacts, not from memory.
    b. **Cross-check prior context for conflicts**: glob `.gjc/_session-{sessionid}/specs/deep-interview-*.md` and other prior specs/plans/context relevant by topic. For each, list points where the consensus plan contradicts, weakens, or expands beyond a previously crystallized decision, constraint, or non-goal. Cite the conflicting artifact and line/section.
@@ -126,38 +126,51 @@ The consensus workflow:
 - On cap: exit code **3**, marker **`PLANNING-STUCK`** (stdout), no silent re-loop, no automatic or explicit ultragoal/team dispatch. Opener budget is `max(index.jsonl openers, on-disk stage-*-{planner,revision}.md count)` so a missing/empty/malformed ledger cannot fail open after prior openers.
 - Headless/CI: treat `PLANNING-STUCK` / exit 3 as terminal planning failure for orchestration/watchdogs.
 - Interactive: retain the best existing plan as a terminal planning result; residual critic findings stay as caveats.
-- Override example (project `.gjc/settings.json`):
-
-```json
-{
-  "gjc": {
-    "ralplan": {
-      "maxIterations": 3
-    }
-  }
-}
+- **Workflow settings precedence** — ralplan reads all of its settings
+  (`gjc.ralplan.maxIterations`, `gjc.ralplan.maxReviewPassesPerLane`,
+  `gjc.ralplan.autoHandoff`) through one shared resolver in this exact order
+  (first valid value wins):
+  1. project `.gjc/config.yml`
+  2. user `<agentDir>/config.yml` (normally `~/.gjc/agent/config.yml`, honoring
+     `GJC_CODING_AGENT_DIR`/`PI_CODING_AGENT_DIR`; XDG applies only to categorized data/state/cache subdirs, never the workflow config path)
+  3. built-in default
+
+  `config.yml` uses the nested (schema) form — `gjc: { ralplan: { maxIterations } }`.
+  Project configuration beats user configuration. The reported `source` is the
+  canonical path of the winning file, or `default`. `config.yml` is the ONLY
+  settings surface: the legacy `settings.json` files (project and config-root)
+  are retired: the config-root `~/.gjc/settings.json` is migrated once into the
+  default global agent `config.yml` and its source removed, while the project
+  `.gjc/settings.json` is retained for non-workflow settings (only its workflow
+  keys are migrated into project `.gjc/config.yml` and no longer read unless a migration target is absent - a migration that could not publish (e.g. a read-only `.gjc`) leaves the retained legacy value effective as the previously configured override until it can publish). **Malformed or
+  invalid explicit settings in any layer exit 2**
+  (`invalid ralplan settings at <path>: <reason>`) — including
+  `gjc.ralplan.maxIterations`, whose former silent fallback to the default is
+  removed.
+- Override example (project `.gjc/config.yml`):
+
+```yaml
+gjc:
+  ralplan:
+    maxIterations: 3
 ```
 
 ## Per-lane review budget (operator contract)
 
 - Default: **1** Architect pass and **1** Critic pass per opener iteration.
-- Override via `gjc.ralplan.maxReviewPassesPerLane`: project `.gjc/settings.json` overrides user settings; the value is an integer **1..10** registered in the public settings schema.
+- Override via `gjc.ralplan.maxReviewPassesPerLane` (integer **1..10**, registered in the public settings schema) using the workflow-settings precedence above; project overrides user.
 - On overflow: exit code **3** with the **`PLANNING-STUCK`** marker and lane-specific JSON/stderr detail.
 - `post-interview`, `adr`, and `final` are always allowed.
 - Identical re-writes dedupe without stuck-signaling — including after a crash between artifact write and ledger append: the identical retry repairs the missing ledger row and returns the dedupe receipt.
 - A new `--run-id` starts a fresh budget.
 - A rule-2-justified blocker routes through a Planner `revision` opener (new iteration, fresh lane budget), never a second same-iteration review pass.
-- Override example (project `.gjc/settings.json`):
-
-```json
-{
-  "gjc": {
-    "ralplan": {
-      "maxIterations": 3,
-      "maxReviewPassesPerLane": 2
-    }
-  }
-}
+- Override example (project `.gjc/config.yml`):
+
+```yaml
+gjc:
+  ralplan:
+    maxIterations: 3
+    maxReviewPassesPerLane: 2
 ```
 
 

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

@@ -18,6 +18,22 @@ Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durabl
 - `.gjc/_session-{sessionid}/ultragoal/ledger.jsonl` (checkpoint and structured steering audit events)
 
 Existing aggregate plans with the legacy enumerated objective are migrated to the stable pointer objective on read, persisted to `goals.json`, retained in `gjcObjectiveAliases` for already-active hidden goal reconciliation, and audited with an `aggregate_objective_migrated` ledger entry.
+- **Nudge budget setting** — the per-story give-up budget
+  (`gjc.ultragoal.nudgeBudget`, default **10**, non-negative integer) is read
+  through one shared resolver in this exact order (first valid value wins):
+  1. project `.gjc/config.yml`
+  2. user `<agentDir>/config.yml` (normally `~/.gjc/agent/config.yml`, honoring
+     `GJC_CODING_AGENT_DIR`/`PI_CODING_AGENT_DIR`; XDG applies only to categorized data/state/cache subdirs, never the workflow config path)
+  3. built-in default
+  `config.yml` uses the nested (schema) form - `gjc: { ultragoal: { nudgeBudget } }`.
+  Project configuration beats user configuration. The reported `source` is the
+  canonical path of the winning file, or `default`. `config.yml` is the ONLY
+  settings surface: the legacy `settings.json` files (project and config-root)
+  are retired: the config-root `~/.gjc/settings.json` is migrated once into the
+  default global agent `config.yml` and its source removed, while the project
+  `.gjc/settings.json` is retained for non-workflow settings (only its workflow
+  keys are migrated into project `.gjc/config.yml` and no longer read unless a migration target is absent - a migration that could not publish (e.g. a read-only `.gjc`) leaves the retained legacy value effective as the previously configured override until it can publish). Invalid optional settings
+  files continue to the next layer or the default (tolerant).
 
 ## Corrupt current-session state recovery
 

package/src/discovery/claude-hooks.ts

@@ -0,0 +1,38 @@
+import * as path from "node:path";
+import { registerProvider } from "../capability";
+import { type Hook, hookCapability } from "../capability/hook";
+import type { LoadContext, LoadResult } from "../capability/types";
+import { createSourceMeta, loadFilesFromDir, SOURCE_PATHS } from "./helpers";
+
+const PROVIDER_ID = "claude";
+const DISPLAY_NAME = "Anthropic Claude";
+const PRIORITY = 80;
+
+async function loadHooks(ctx: LoadContext): Promise<LoadResult<Hook>> {
+	const items: Hook[] = [];
+	const warnings: string[] = [];
+	const projectHooksDir = path.join(ctx.cwd, SOURCE_PATHS.claude.projectDir, "hooks");
+	for (const hookType of ["pre", "post"] as const) {
+		const result = await loadFilesFromDir<Hook>(ctx, path.join(projectHooksDir, hookType), PROVIDER_ID, "project", {
+			transform: (name, _content, filePath) => ({
+				name,
+				path: filePath,
+				type: hookType,
+				tool: name.replace(/\.(sh|bash|zsh|fish|ts|js)$/, ""),
+				level: "project",
+				_source: createSourceMeta(PROVIDER_ID, filePath, "project"),
+			}),
+		});
+		items.push(...result.items);
+		warnings.push(...(result.warnings ?? []));
+	}
+	return { items, warnings };
+}
+
+registerProvider<Hook>(hookCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load hooks from project .claude/hooks/pre/ and .claude/hooks/post/",
+	priority: PRIORITY,
+	load: loadHooks,
+});