@event4u/agent-config 2.26.0 → 3.0.0

package/dist/server/routes/settings.js

@@ -0,0 +1,155 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { settingsSchema } from '../schemas/settings.js';
+import { parseYaml, mergeIntoTemplate, diffValues } from '../io/yamlIO.js';
+import { writeAtomic } from '../io/atomicWrite.js';
+// Computed once — Zod → JSON Schema conversion is pure and the schema is static.
+const SETTINGS_JSON_SCHEMA = zodToJsonSchema(settingsSchema, {
+    name: 'AgentSettings',
+    $refStrategy: 'none',
+    target: 'jsonSchema7',
+});
+const SETTINGS_RELATIVE = '.agent-settings.yml';
+function settingsPath(root) {
+    return join(root, SETTINGS_RELATIVE);
+}
+async function readSettingsFrom(root) {
+    const path = settingsPath(root);
+    let stat;
+    let raw;
+    try {
+        [stat, raw] = await Promise.all([fs.stat(path), fs.readFile(path, 'utf8')]);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const values = parseYaml(raw);
+    return { raw, values, mtimeMs: Math.trunc(stat.mtimeMs) };
+}
+/**
+ * Read `.agent-settings.yml` from `writeRoot`, falling back to
+ * `legacyReadRoot` on ENOENT. A hit on the fallback is what makes the
+ * silent-migration story work: the next PUT writes to `writeRoot` and
+ * the legacy file is no longer consulted.
+ */
+async function readSettings(writeRoot, legacyReadRoot) {
+    const primary = await readSettingsFrom(writeRoot);
+    if (primary !== null)
+        return primary;
+    if (legacyReadRoot && legacyReadRoot !== writeRoot) {
+        return readSettingsFrom(legacyReadRoot);
+    }
+    return null;
+}
+function zodIssuesToFields(issues) {
+    return issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message }));
+}
+function readIfUnmodified(header) {
+    if (typeof header !== 'string')
+        return null;
+    const n = Number.parseInt(header, 10);
+    return Number.isFinite(n) ? n : null;
+}
+export function settingsRoute(opts) {
+    const plugin = async (app) => {
+        app.get('/api/v1/settings', async (_request, reply) => {
+            try {
+                const state = await readSettings(opts.writeRoot, opts.legacyReadRoot);
+                if (state === null) {
+                    await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'settings file missing' } });
+                    return reply;
+                }
+                return {
+                    values: state.values,
+                    lastModified: state.mtimeMs,
+                    path: SETTINGS_RELATIVE,
+                    schema: SETTINGS_JSON_SCHEMA,
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'YAML parse failed';
+                await reply.code(500).send({ error: { code: 'YAML_PARSE', message } });
+                return reply;
+            }
+        });
+        app.post('/api/v1/settings/diff', async (request, reply) => {
+            const body = (request.body ?? {});
+            const parsed = settingsSchema.safeParse(body.values);
+            if (!parsed.success) {
+                await reply.code(422).send({
+                    error: { code: 'VALIDATION', message: 'invalid settings', fields: zodIssuesToFields(parsed.error.issues) },
+                });
+                return reply;
+            }
+            const current = await readSettings(opts.writeRoot, opts.legacyReadRoot);
+            if (current === null) {
+                await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'settings file missing' } });
+                return reply;
+            }
+            const ius = typeof body.ifUnmodifiedSince === 'number' ? body.ifUnmodifiedSince : null;
+            if (ius !== null && ius < current.mtimeMs) {
+                await reply.code(409).send({
+                    error: { code: 'CONFLICT', message: 'on-disk file has been modified' },
+                    current: { values: current.values, lastModified: current.mtimeMs },
+                });
+                return reply;
+            }
+            const changes = diffValues(current.values, parsed.data);
+            return { changes };
+        });
+        app.put('/api/v1/settings', async (request, reply) => {
+            const ius = readIfUnmodified(request.headers['if-unmodified-since']);
+            if (ius === null) {
+                await reply.code(412).send({ error: { code: 'PRECONDITION_REQUIRED', message: 'If-Unmodified-Since header required' } });
+                return reply;
+            }
+            const body = (request.body ?? {});
+            const parsed = settingsSchema.safeParse(body.values);
+            if (!parsed.success) {
+                await reply.code(422).send({
+                    error: { code: 'VALIDATION', message: 'invalid settings', fields: zodIssuesToFields(parsed.error.issues) },
+                });
+                return reply;
+            }
+            const current = await readSettings(opts.writeRoot, opts.legacyReadRoot);
+            if (current === null) {
+                await reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'settings file missing' } });
+                return reply;
+            }
+            if (ius < current.mtimeMs) {
+                await reply.code(409).send({
+                    error: { code: 'CONFLICT', message: 'on-disk file has been modified' },
+                    current: { values: current.values, lastModified: current.mtimeMs },
+                });
+                return reply;
+            }
+            try {
+                const merged = mergeIntoTemplate(current.raw, parsed.data);
+                if (opts.dryRun === true) {
+                    // No disk write, no Last-Modified bump — surface the
+                    // rendered body so the maintainer sees what a real
+                    // PUT would have written.
+                    return {
+                        dryRun: true,
+                        lastModified: current.mtimeMs,
+                        preview: { path: SETTINGS_RELATIVE, body: merged },
+                    };
+                }
+                const path = settingsPath(opts.writeRoot);
+                await writeAtomic(path, merged, { mode: 0o600 });
+                const stat = await fs.stat(path);
+                return { lastModified: Math.trunc(stat.mtimeMs), writtenPaths: [SETTINGS_RELATIVE] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'atomic write failed';
+                await reply.code(500).send({ error: { code: 'ATOMIC_WRITE', message } });
+                return reply;
+            }
+        });
+    };
+    return plugin;
+}
+//# sourceMappingURL=settings.js.map

package/dist/server/routes/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../../src/server/routes/settings.ts"],"names":[],"mappings":"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"}

package/dist/server/routes/userMd.js

@@ -0,0 +1,117 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { userMdSchema } from '../../shared/userMd/schema.js';
+import { writeAtomic } from '../io/atomicWrite.js';
+import { PACKAGE_ROOT } from '../../cli/paths.js';
+const USER_MD_RELATIVE = '.agent-user.md';
+const DEFAULT_TEMPLATE = join(PACKAGE_ROOT, 'templates', 'agent-user.md');
+function userMdPath(root) {
+    return join(root, USER_MD_RELATIVE);
+}
+async function readUserMdFrom(root) {
+    const path = userMdPath(root);
+    try {
+        const [stat, body] = await Promise.all([fs.stat(path), fs.readFile(path, 'utf8')]);
+        return { body, mtimeMs: Math.trunc(stat.mtimeMs) };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/**
+ * Read `.agent-user.md` from `writeRoot`, falling back to `legacyReadRoot`
+ * on ENOENT. Mirrors the settings route — see `readSettings` for the
+ * silent-migration rationale.
+ */
+async function readUserMd(writeRoot, legacyReadRoot) {
+    const primary = await readUserMdFrom(writeRoot);
+    if (primary !== null)
+        return primary;
+    if (legacyReadRoot && legacyReadRoot !== writeRoot) {
+        return readUserMdFrom(legacyReadRoot);
+    }
+    return null;
+}
+function readIfUnmodified(header) {
+    if (typeof header !== 'string')
+        return null;
+    const n = Number.parseInt(header, 10);
+    return Number.isFinite(n) ? n : null;
+}
+function zodIssuesToFields(issues) {
+    return issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message }));
+}
+export function userMdRoute(opts) {
+    const templatePath = opts.templatePath ?? DEFAULT_TEMPLATE;
+    const plugin = async (app) => {
+        app.get('/api/v1/user-md', async (_request, _reply) => {
+            const state = await readUserMd(opts.writeRoot, opts.legacyReadRoot);
+            if (state === null) {
+                return { body: '', exists: false, lastModified: null };
+            }
+            return { body: state.body, exists: true, lastModified: state.mtimeMs };
+        });
+        app.get('/api/v1/user-md/template', async (_request, reply) => {
+            try {
+                const body = await fs.readFile(templatePath, 'utf8');
+                return { body };
+            }
+            catch (err) {
+                if (err.code === 'ENOENT') {
+                    await reply.code(204).send();
+                    return reply;
+                }
+                throw err;
+            }
+        });
+        app.put('/api/v1/user-md', async (request, reply) => {
+            const body = (request.body ?? {});
+            const parsed = userMdSchema.safeParse(body);
+            if (!parsed.success) {
+                await reply.code(422).send({
+                    error: { code: 'VALIDATION', message: 'invalid user-md body', fields: zodIssuesToFields(parsed.error.issues) },
+                });
+                return reply;
+            }
+            const ius = readIfUnmodified(request.headers['if-unmodified-since']);
+            const current = await readUserMd(opts.writeRoot, opts.legacyReadRoot);
+            if (current !== null) {
+                if (ius === null) {
+                    await reply.code(412).send({
+                        error: { code: 'PRECONDITION_REQUIRED', message: 'If-Unmodified-Since header required for existing file' },
+                    });
+                    return reply;
+                }
+                if (ius < current.mtimeMs) {
+                    await reply.code(409).send({
+                        error: { code: 'CONFLICT', message: 'on-disk file has been modified' },
+                        current: { body: current.body, lastModified: current.mtimeMs },
+                    });
+                    return reply;
+                }
+            }
+            try {
+                if (opts.dryRun === true) {
+                    return {
+                        dryRun: true,
+                        lastModified: current?.mtimeMs ?? null,
+                        preview: { path: USER_MD_RELATIVE, body: parsed.data.body },
+                    };
+                }
+                const path = userMdPath(opts.writeRoot);
+                await writeAtomic(path, parsed.data.body, { mode: 0o600 });
+                const stat = await fs.stat(path);
+                return { lastModified: Math.trunc(stat.mtimeMs), writtenPaths: [USER_MD_RELATIVE] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'atomic write failed';
+                await reply.code(500).send({ error: { code: 'ATOMIC_WRITE', message } });
+                return reply;
+            }
+        });
+    };
+    return plugin;
+}
+//# sourceMappingURL=userMd.js.map

package/dist/server/routes/userMd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userMd.js","sourceRoot":"","sources":["../../../src/server/routes/userMd.ts"],"names":[],"mappings":"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"}

package/dist/server/routes/wizard.js

@@ -0,0 +1,138 @@
+import { promises as fs } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { z } from 'zod';
+import { settingsSchema } from '../schemas/settings.js';
+import { userMdSchema } from '../../shared/userMd/schema.js';
+import { mergeIntoTemplate } from '../io/yamlIO.js';
+import { commitMulti } from '../io/atomicMultiWrite.js';
+import { writeAtomic } from '../io/atomicWrite.js';
+const STATE_REL = join('state', 'wizard-state.json');
+const SETTINGS_REL = '.agent-settings.yml';
+const USER_MD_REL = '.agent-user.md';
+// Step count mirrors the UI's `WIZARD_STEPS` array in `src/ui/wizard/steps.ts`
+// and the chat-side `~/.claude/skills/onboard/SKILL.md`. Bump in lockstep.
+const DEFAULT_TOTAL_STEPS = 7;
+const wizardStateSchema = z.object({
+    step: z.number().int().min(0),
+    totalSteps: z.number().int().min(1).optional(),
+    partial: z.record(z.unknown()).default({}),
+    startedAt: z.string().nullable().default(null),
+});
+function statePath(root) {
+    return join(root, STATE_REL);
+}
+async function readState(root) {
+    try {
+        const raw = await fs.readFile(statePath(root), 'utf8');
+        const parsed = wizardStateSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        return null;
+    }
+}
+async function writeState(root, state) {
+    const path = statePath(root);
+    await fs.mkdir(dirname(path), { recursive: true });
+    await writeAtomic(path, JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+async function readTemplate(packageRoot) {
+    return fs.readFile(join(packageRoot, 'config', 'agent-settings.template.yml'), 'utf8');
+}
+function zodIssuesToFields(issues) {
+    return issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message }));
+}
+export function wizardRoute(opts) {
+    const totalSteps = opts.totalSteps ?? DEFAULT_TOTAL_STEPS;
+    const dryRun = opts.dryRun === true;
+    // Per-process in-memory state for dry-run. One CLI invocation = one
+    // server = one Map; cross-session leakage is impossible because each
+    // `agent-config setup --dry-run` mints a fresh server. See § Dry-run
+    // state contract in the roadmap.
+    let memState = null;
+    const plugin = async (app) => {
+        app.get('/api/v1/wizard/state', async () => {
+            // Dry-run: in-memory write wins; fall back to disk so an
+            // in-progress real run can be previewed.
+            const existing = dryRun ? (memState ?? await readState(opts.writeRoot)) : await readState(opts.writeRoot);
+            if (existing === null) {
+                return { step: 0, totalSteps, partial: {}, startedAt: null };
+            }
+            return { ...existing, totalSteps: existing.totalSteps ?? totalSteps };
+        });
+        app.post('/api/v1/wizard/state', async (request, reply) => {
+            const body = (request.body ?? {});
+            const parsed = wizardStateSchema.safeParse({
+                step: body.step,
+                partial: body.partial ?? {},
+                totalSteps: body.totalSteps ?? totalSteps,
+                startedAt: body.startedAt ?? new Date().toISOString(),
+            });
+            if (!parsed.success) {
+                await reply.code(422).send({
+                    error: { code: 'VALIDATION', message: 'invalid wizard state', fields: zodIssuesToFields(parsed.error.issues) },
+                });
+                return reply;
+            }
+            if (dryRun) {
+                memState = parsed.data;
+                return { ok: true, dryRun: true };
+            }
+            await writeState(opts.writeRoot, parsed.data);
+            return { ok: true };
+        });
+        app.post('/api/v1/wizard/finish', async (request, reply) => {
+            const body = (request.body ?? {});
+            const settingsParsed = settingsSchema.safeParse(body.settings);
+            if (!settingsParsed.success) {
+                await reply.code(422).send({
+                    error: { code: 'VALIDATION', message: 'invalid settings', fields: zodIssuesToFields(settingsParsed.error.issues) },
+                });
+                return reply;
+            }
+            // Wire shape: `userMd` is a bare string. The schema wraps it
+            // as `{ body }` for length + frontmatter checks.
+            const userMdParsed = body.userMd === undefined || body.userMd === null
+                ? null
+                : userMdSchema.safeParse({ body: body.userMd });
+            if (userMdParsed && !userMdParsed.success) {
+                await reply.code(422).send({
+                    error: { code: 'VALIDATION', message: 'invalid user-md', fields: zodIssuesToFields(userMdParsed.error.issues) },
+                });
+                return reply;
+            }
+            try {
+                const template = await readTemplate(opts.packageRoot);
+                const settingsBody = mergeIntoTemplate(template, settingsParsed.data);
+                const userMdBody = userMdParsed && userMdParsed.success ? userMdParsed.data.body : null;
+                if (dryRun) {
+                    // No disk write; surface the rendered would-be bodies
+                    // so the maintainer sees the actual diff target.
+                    return {
+                        ok: true,
+                        dryRun: true,
+                        preview: { settingsYaml: settingsBody, userMd: userMdBody },
+                    };
+                }
+                const payloads = [
+                    { target: join(opts.writeRoot, SETTINGS_REL), contents: settingsBody, mode: 0o600 },
+                ];
+                if (userMdBody !== null) {
+                    payloads.push({ target: join(opts.writeRoot, USER_MD_REL), contents: userMdBody, mode: 0o600 });
+                }
+                const { txnId } = await commitMulti(payloads, { writeRoot: opts.writeRoot });
+                await fs.unlink(statePath(opts.writeRoot)).catch(() => undefined);
+                return { writtenPaths: payloads.map((p) => p.target), txnId };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : '2PC commit failed';
+                await reply.code(500).send({ error: { code: 'TXN_PARTIAL', message } });
+                return reply;
+            }
+        });
+    };
+    return plugin;
+}
+//# sourceMappingURL=wizard.js.map

package/dist/server/routes/wizard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.js","sourceRoot":"","sources":["../../../src/server/routes/wizard.ts"],"names":[],"mappings":"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"}

package/dist/server/schemas/settings.js

@@ -0,0 +1,138 @@
+/**
+ * Zod schema for `.agent-settings.yml`.
+ *
+ * Source of truth: `config/agent-settings.template.yml`. Every leaf has a
+ * matching template key; the schema↔template parity test
+ * (`tests/server/schemas/parity.test.ts`) walks both trees and asserts the
+ * Zod schema covers every template path. New template keys without schema
+ * additions fail CI.
+ *
+ * Render strategy: depth ≤ 2. The form renderer (`SchemaForm`, Phase 2)
+ * recurses one level into nested objects; deeper trees fail render-time.
+ */
+import { z } from 'zod';
+const costProfile = z.enum(['minimal', 'balanced', 'full', 'custom']);
+const enforcementMode = z.enum(['advisory', 'hard-stop']);
+const autonomyMode = z.enum(['on', 'off', 'auto']);
+const userType = z.enum(['', 'consultant', 'creator', 'developer', 'finance', 'founder', 'gtm', 'ops']);
+const accessStyle = z.enum(['getters_setters', 'get_attribute', 'magic_properties']);
+const chatFreq = z.enum(['per_turn', 'per_phase', 'per_tool']);
+const chatOverflow = z.enum(['rotate', 'compress']);
+const qualityCadence = z.enum(['end_of_roadmap', 'per_phase', 'per_step']);
+const regenCadence = z.enum(['per_step', 'every_5_steps', 'phase_boundary']);
+const worktreeMode = z.enum(['off', 'on', 'ask']);
+const replyMethod = z.enum(['replies_endpoint', 'create_review_comment', 'auto']);
+const confidenceBand = z.enum(['off', 'low', 'medium', 'high']);
+const onBlock = z.enum(['stop', 'ask', 'warn']);
+const onBlockFallback = z.enum(['stop', 'warn']);
+export const settingsSchema = z.object({
+    agent_config_version: z.string().default('').describe('Pin the package to an exact semver (e.g. "1.4.2") so all teammates load the same skill / rule set. Leave empty to track whatever is installed locally — useful for the maintainers of this package, risky for production projects.'),
+    cost_profile: costProfile.default('balanced').describe('Master switch for which rule tiers load and how cautiously the agent spends tokens. minimal = only the 9 kernel rules (cheapest, fewest guardrails). balanced = kernel + tier-1 (recommended default). full = kernel + tier-1 + tier-2 (most guardrails, highest token cost). custom = roll your own in agents/overrides/.'),
+    cost: z.object({
+        budgets: z.object({
+            daily: z.number().min(0).default(0).describe('Daily USD ceiling across all model calls. The agent warns at 50% / 75% / 90% and either stops or warns at 100% depending on cost.enforcement. Set 0 to disable the daily budget entirely.'),
+            weekly: z.number().min(0).default(0).describe('Rolling 7-day USD ceiling. Same alert ladder as cost.budgets.daily but useful when work bursts unevenly across the week. Set 0 to disable.'),
+            monthly: z.number().min(0).default(0).describe('Calendar-month USD ceiling. Pairs with cost.enforcement = hard-stop for a hard cap on agent spend before the next billing cycle. Set 0 to disable.'),
+        }),
+        enforcement: enforcementMode.default('advisory').describe('What happens when a budget hits 100%. advisory = show a banner, keep working (default — never blocks an active task). hard-stop = refuse further model calls until the budget resets or you raise the ceiling.'),
+    }),
+    personal: z.object({
+        ide: z.string().default('').describe('CLI binary your IDE registers (code, code-insiders, phpstorm, cursor, windsurf, idea, subl, …). Used by the file-editor skill to open edited files. Leave empty to disable IDE integration.'),
+        open_edited_files: z.boolean().default(false).describe('After the agent edits a file, run `<ide> <path>` to surface it in your editor immediately. Off by default to avoid window-stealing during long agent runs.'),
+        user_name: z.string().default('').describe('How the agent addresses you in chat ("Matze", "Sarah"). Legacy fallback only — the source of truth is the YAML frontmatter in .agent-user.md, which also carries pronouns, working hours, and tone preferences.'),
+        rtk_installed: z.boolean().default(false).describe('Does this machine have rtk (Rust Token Killer, https://github.com/event4u-app/rtk) on PATH? When true the agent wraps verbose CLI output (git, tests, linters, docker, npm, composer) with rtk for ~60-90% token savings. Leave false if rtk is missing — the agent falls back to tail / grep.'),
+        minimal_output: z.boolean().default(true).describe('Prefer short bullets and tables (true, default) vs verbose prose with rationale (false). Affects every chat reply; flip to false during debugging when you want the agent to think out loud.'),
+        play_by_play: z.boolean().default(false).describe('Narrate intermediate findings between tool calls ("Found it.", "Let me check Y."). Off by default — most users find it noisy. Turn on when you want to follow the agent\'s reasoning step by step.'),
+        pr_comment_bot_icon: z.boolean().default(false).describe('Prefix every PR review-comment reply with 🤖 so humans can tell agent-authored comments apart from teammate comments at a glance. Cosmetic only; the comment body itself never changes.'),
+        autonomy: autonomyMode.default('auto').describe('How aggressively the agent suppresses trivial workflow questions ("commit now?", "open PR?"). on = silently pick the sensible default. off = always ask. auto (default) = decide per project, on for solo / off when collaborators are involved. The Hard Floor (prod, deploys, bulk deletes) ignores this setting and always asks.'),
+        user_type: userType.default('').describe('Optional persona axis used by the skill-suggester to surface the relevant subset (consultant / creator / developer / finance / founder / gtm / ops). Empty = no filter, all skills available. You can change this any time without re-running setup.'),
+    }),
+    project: z.object({
+        pr_template: z.string().default('.github/pull_request_template.md').describe('Path (relative to project root) to the PR-description template the agent fills in before opening a pull request. Override only if your repo keeps the template somewhere non-standard.'),
+        upstream_repo: z.string().default('').describe('GitHub slug (owner/repo) the upstream-contribute skill targets when you ask the agent to push a learning back to the shared agent-config package. Empty = improvement PRs are disabled.'),
+        improvement_pr_branch_prefix: z.string().default('improve/agent-').describe('Branch-name prefix for improvement PRs the agent opens against project.upstream_repo (e.g. "improve/agent-add-react-skill"). Pick a prefix your repo conventions allow.'),
+    }),
+    github: z.object({
+        pr_reply_method: replyMethod.default('create_review_comment').describe('How the agent replies to PR review comments. create_review_comment = post a new review comment (works on every GitHub plan). replies_endpoint = thread the reply under the original comment (needs the newer REST endpoint). auto = detect at runtime, prefer threaded replies when available.'),
+    }),
+    augment: z.object({
+        rules_use_symlinks: z.boolean().default(false).describe('When true, .augment/rules/*.md are symlinks into .agent-src/rules/ — edits flow back to source on save. When false (default), they are copies — safer on Windows and shared volumes, but rule edits in .augment/ are lost on the next `task sync`.'),
+    }),
+    eloquent: z.object({
+        access_style: accessStyle.default('getters_setters').describe('How the agent writes Laravel Eloquent property access. getters_setters = explicit getName() / setName() methods (most refactor-safe). get_attribute = $model->getAttribute("name") (verbose but explicit). magic_properties = $model->name (idiomatic but harder to grep).'),
+    }),
+    chat_history: z.object({
+        enabled: z.boolean().default(true).describe('Persist a structured log of every chat turn to .agent-config/chat-history/ so /chat-history:show, :import, and :learn can replay sessions. Turn off if you never want chat transcripts on disk.'),
+        frequency: chatFreq.default('per_turn').describe('How often the chat-history writer flushes to disk. per_turn = after every user / agent exchange (default, lowest data loss on crash). per_phase = at phase boundaries (cheaper I/O). per_tool = after every tool call (highest fidelity, noisiest log).'),
+        max_size_kb: z.number().int().min(0).default(2048).describe('Maximum size (KB) of the active chat-history file before chat_history.on_overflow kicks in. Set 0 to disable rotation / compression entirely (file grows forever).'),
+        on_overflow: chatOverflow.default('rotate').describe('What happens when chat_history.max_size_kb is hit. rotate = move the current log aside and start fresh (default). compress = caveman-compress the oldest entries in place to keep recent context.'),
+        text_limits: z.object({
+            user: z.number().int().min(0).default(0).describe('Per-message character cap for user inputs in the chat-history log. 0 = log verbatim (default). Raise above 0 only if your prompts contain large pasted artefacts you do not want stored.'),
+            agent: z.number().int().min(0).default(5000).describe('Per-message character cap for agent replies in the chat-history log. Truncates with an ellipsis past the cap. Lower to shrink history files, raise for long-reasoning replies.'),
+            tool: z.number().int().min(0).default(200).describe('Per-call character cap for tool input / output blobs in the chat-history log. The default 200 keeps history files compact while preserving enough signal to replay a session.'),
+            phase: z.number().int().min(0).default(200).describe('Per-marker character cap for phase markers (Phase=Refine, Phase=Plan, …) in the chat-history log. Rarely needs tuning.'),
+        }),
+    }),
+    pipelines: z.object({
+        skill_improvement: z.boolean().default(true).describe('After a meaningful task the agent proposes a learning-capture turn (new skill, rule tweak, guideline). Turn off if you find the prompts noisy — you can still run /memory:promote manually.'),
+    }),
+    roadmap: z.object({
+        quality_cadence: qualityCadence.default('end_of_roadmap').describe('When the agent runs the full quality / test suite during /roadmap:process-* runs. end_of_roadmap = once, after the last step (fastest, default). per_phase = after each phase boundary. per_step = after every single step (slowest, highest confidence).'),
+        dashboard_regen_cadence: regenCadence.default('per_step').describe('How often the agent regenerates agents/roadmaps/dashboard.md during a roadmap run. per_step = after every step (default, freshest dashboard). every_5_steps = batch the regen. phase_boundary = only at phase edges.'),
+        horizon_weeks: z.number().int().min(0).default(0).describe('Optional planning horizon (weeks) the agent shows in roadmap framing ("next 4 weeks"). Set 0 to omit the horizon — most teams prefer to ship without a hardcoded window.'),
+    }),
+    quality: z.object({
+        local_auto_run: z.boolean().default(true).describe('Run quality tools (linters, type-checks, formatters) and the local test suite autonomously after edits. Turn off if your toolchain is slow and you prefer to invoke quality runs manually with /quality-fix.'),
+        wait_for_remote_ci: z.boolean().default(false).describe('After pushing a branch, poll the remote CI provider (GitHub Actions, GitLab CI) and surface failures inline. Off by default — useful when local CI does not cover everything the remote pipeline runs.'),
+    }),
+    subagents: z.object({
+        implementer_model: z.string().default('').describe('Override the model the orchestrator dispatches to subagents that write code (e.g. claude-sonnet-4, gpt-5). Empty (default) = inherit the session\'s primary model — cheapest and usually right.'),
+        judge_model: z.string().default('').describe('Override the model used for review / judge subagents that critique implementer output. Empty (default) = one tier above the implementer model — picks up nuance the implementer missed.'),
+        max_parallel: z.number().int().min(1).default(3).describe('Hard cap on subagents running in parallel during /do-in-parallel, /do-competitively, and /judge runs. Raise for faster fan-out, lower if you hit rate limits or want lower token spend.'),
+    }),
+    worktrees: z.object({
+        mode: worktreeMode.default('ask').describe('When the agent considers a parallel `git worktree` for risky / large work. ask (default) = surface a numbered option and wait. on = spawn worktrees autonomously. off = never use worktrees, edit in place.'),
+    }),
+    onboarding: z.object({
+        onboarded: z.boolean().default(false).describe('Set to true once the developer has completed `agent-config setup`. The onboarding-gate rule blocks the first turn of every chat until this is true. Toggle back to false to re-trigger the wizard.'),
+    }),
+    commands: z.object({
+        suggestion: z.object({
+            enabled: z.boolean().default(true).describe('Master switch for the slash-command suggestion layer. When on, the agent offers numbered options ("did you mean /commit?") instead of guessing. Turn off if you prefer to type every command yourself.'),
+            confidence_floor: z.number().min(0).max(1).default(0.6).describe('Minimum semantic-match score (0.0–1.0) before a command is offered as a suggestion. 0.6 (default) balances precision and recall. Raise toward 0.8 for fewer false positives, lower for broader hints.'),
+            cooldown_seconds: z.number().int().min(0).default(600).describe('How long (seconds) the suggester waits before offering the same command again after you ignored it. Default 600s (10 min) keeps the agent from nagging. Set 0 to disable the cooldown.'),
+            max_options: z.number().int().min(0).default(4).describe('Maximum number of command suggestions shown in a single numbered-options block, before the "Proceed as-is" escape. Lower for terser prompts, raise if you regularly want broader fan-out.'),
+            blocklist: z.array(z.string()).default([]).describe('Slash-command names that should never be suggested, one per line (e.g. "commit", "create-pr"). Useful if a command misfires on your common phrasing.'),
+        }),
+        create_pr: z.object({
+            preview_description: z.boolean().default(false).describe('When /create-pr runs, show the generated title and body and wait for confirmation before opening the PR. Off by default (zero-friction PR creation); turn on if you want a last-look gate.'),
+        }),
+    }),
+    memory: z.object({
+        review_threshold: z.number().int().min(0).default(10).describe('Maximum number of memory entries /memory:load surfaces inline before falling back to a summary view. Default 10 keeps the chat readable. Raise to see more candidates, lower to keep the context tight.'),
+        redact_patterns: z.array(z.string()).default([]).describe('Regex patterns (one per line) that scrub matches from chat-history transcripts and memory before they hit disk. Use for secrets, customer names, internal URLs. Patterns are anchored and case-insensitive.'),
+    }),
+    hooks: z.object({
+        concern_budget: z.object({
+            max_per_event: z.number().int().min(1).default(8).describe('Maximum number of concerns (issues / warnings) a single hook may raise per (platform, event) pair before the hook is rate-limited. Default 8 prevents noisy hooks from drowning out high-signal ones.'),
+            tier1_concerns: z.array(z.string()).default([]).describe('Concern IDs (one per line) that are allowed to block the run on failure rather than warn. Reserved for high-confidence guards — leave empty unless you maintain custom hooks.'),
+            hard_fail: z.boolean().default(false).describe('When a hook exceeds hooks.concern_budget.max_per_event, fail the run (true) instead of warning and continuing (false, default). Turn on in CI when you want hook quality to gate merges.'),
+        }),
+    }),
+    decision_engine: z.object({
+        surface_traces: z.boolean().default(false).describe('Emit DecisionTraceHook events that surface why the agent picked one option over another. Useful when debugging unexpected choices; off by default to keep chat noise low.'),
+        min_confidence: confidenceBand.default('off').describe('During Phase=Plan, refuse to advance to Phase=Implement if confidence is below this band. off (default) = no gate. low / medium / high = raise the floor; on miss, decision_engine.on_block decides what happens.'),
+        block_on_risk: confidenceBand.default('off').describe('During Phase=Implement, refuse to act when the risk class meets or exceeds this band. off (default) = no gate. low / medium / high = stricter ceilings; pairs with decision_engine.on_block.'),
+        require_memory_hits: z.boolean().default(false).describe('During Phase=Refine, require at least one relevant memory hit (skill, ADR, past decision) before the agent proceeds. Off by default; turn on for highly conventional codebases where memory should always inform decisions.'),
+        on_block: onBlock.default('stop').describe('What the decision engine does when a gate (min_confidence / block_on_risk / require_memory_hits) fires. stop (default) = halt and surface the reason. ask = present numbered options. warn = log and continue.'),
+        ask_timeout_seconds: z.number().int().min(0).default(30).describe('Non-TTY timeout (seconds) for decision_engine.on_block = ask. After this elapses without input, decision_engine.on_block_fallback takes over. Default 30s; raise for slow human review, 0 = wait forever.'),
+        on_block_fallback: onBlockFallback.default('stop').describe('Resolution when decision_engine.on_block = ask times out (see decision_engine.ask_timeout_seconds). stop (default) = halt the run. warn = log and continue with the agent\'s best guess.'),
+    }),
+    update_check: z.object({
+        enabled: z.boolean().default(true).describe('Once per day the agent checks the npm registry for a newer agent-config release and surfaces a one-line banner if one exists. Turn off in air-gapped environments or to silence the banner.'),
+    }),
+    explain: z.object({
+        enable_last: z.boolean().default(true).describe('Enable the `agent-config explain last` command, which prints the reasoning behind the agent\'s most recent decision (last tool call, last suggestion). Disable if you never use it and want a smaller CLI surface.'),
+    }),
+});
+//# sourceMappingURL=settings.js.map

package/dist/server/schemas/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../../src/server/schemas/settings.ts"],"names":[],"mappings":"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"}