@event4u/agent-config 16.2.0 → 16.4.0

package/dist/server/schemas/settings.js

@@ -20,22 +20,19 @@ const profileId = z.enum(['developer', 'content_creator', 'founder', 'agency', '
 const accessStyle = z.enum(['getters_setters', 'get_attribute', 'magic_properties']);
 const chatFreq = z.enum(['per_turn', 'per_phase', 'per_tool']);
 const qualityCadence = z.enum(['end_of_roadmap', 'per_phase', 'per_step']);
-const regenCadence = z.enum(['per_step', 'every_5_steps', 'phase_boundary']);
 const fidelityMode = z.enum(['strict', 'structural', 'hard-floor']);
-const crossSourceMode = z.enum(['on', 'auto', 'off']);
-const richSkillsMode = z.enum(['on', 'ask', 'off']);
 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']);
 const modelAutoSwitch = z.enum(['auto', 'suggest', 'off']);
 const leanProjectionMode = z.enum(['eager-all', 'thin', 'delivery']);
 const leanProjectionHost = z.enum(['claude-code', 'cursor', 'cline']);
 const projectionMode = z.enum(['legacy-all', 'scoped']);
-const memoryCadence = z.enum(['auto', 'always', 'never']);
 const projectAudience = z.enum(['self', 'internal', 'client', 'public']);
 const deliveryMerge = z.enum(['off', 'on-green']);
 const prTopology = z.enum(['single', 'stacked']);
+const gitCommitFormat = z.enum(['ticket-scope', 'ticket-conventional']);
+const gitUpdateStrategy = z.enum(['merge', 'rebase']);
 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.'),
     profile: z.object({
@@ -79,20 +76,21 @@ export const settingsSchema = 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.'),
         rtk_installed: z.boolean().default(false).describe('Does this machine have rtk (Rust Token Killer, a third-party Apache-2.0 tool: https://github.com/rtk-ai/rtk) on PATH — verified as the real Token Killer, not the unrelated Rust Type Kit that shares the binary name? When true the agent wraps verbose CLI output (git, tests, linters, docker, npm, composer) with rtk (upstream reports 60-90% token savings — their estimate). Leave false if rtk is missing — the agent falls back to tail / grep. The wizard overwrites this from a live two-stage probe (PATH presence + `rtk gain` identity check).'),
-        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.'),
         canary_name: z.string().default('').describe('Session canary — the name the agent addresses you with at the start of every new task (e.g. "Alex"). When the greeting silently disappears, the context window is degrading: start a fresh conversation. Also keeps the reply-close markers (end-summary, PR URL as literal last line) alive. Empty = fall back to the user-global canary_name, then to identity.name from the setup wizard; no name anywhere = off. See rules/session-canary.md.'),
-        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.'),
         pr_progress_comments: z.boolean().default(false).describe('Permit the agent to post unsolicited progress / status comments on an open PR (e.g. "CI fix iteration #2", "still blocked on workflow scope"). Default off — most teammates find them noisy. User-invoked flows (/fix:pr-comments, /create-pr, /code-review, explicit "post a comment that …") are NOT gated by this setting. See rules/no-pr-progress-comments.md.'),
         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.'),
         audience: projectAudience.default('public').describe('Who this project is built for — read by the demand gate (§ 8-pre of docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md), whose L0-L4 ladder measures MARKET demand and is meaningless where no market is intended. self = a tool its maintainer builds for themselves; the gate is inert and work is classified L-self (build) instead of being deferred for lack of a user population nobody wants. internal = a team tool; only "what breaks without it?" survives. client = built for a named client, who is the requester rather than a market segment. public (default) = a product with an intended market; full three-question gate, behaviour unchanged from before this key existed.'),
     }),
+    git: z.object({
+        commit_format: gitCommitFormat.default('ticket-scope').describe('Where a ticket id goes in a commit subject. ticket-scope (default) = the ticket is the Conventional-Commits scope, `feat(DEV-1234): add export filter` — the behaviour every install had before this key existed. ticket-conventional = the ticket leads the subject and the scope names the system area, `DEV-1234 feat(exporter): add export filter`; a ticket is then never a scope. Without a ticket both shapes are plain Conventional Commits. A commit-linting config in the repository (commitlint, a commit-msg hook) outranks this key.'),
+        branch_pattern: z.string().default('{type}/{slug}').describe('Shape of a branch name the agent creates. Placeholders: {type} (feat, fix, …), {ticket} (e.g. DEV-1234), {slug} (short kebab-case description). Default {type}/{slug}. {slug} is required, and characters outside the placeholders are limited to A-Z a-z 0-9 . _ / - so a rendered name is safe in a command; agent-config git:convention show reports anything else as invalid. A team that names branches after the ticket sets {ticket}-{slug}. A placeholder with no value is dropped together with the separator that follows it, or the one before it when it is last, so no name starts or ends with a separator ({type}/{ticket}-{slug} without a ticket gives feat/slug). Reading a ticket back out of an existing branch never depends on this pattern.'),
+        update_strategy: gitUpdateStrategy.default('merge').describe('How a feature branch is brought up to date with its base. merge (default) = merge the base into the branch, as before this key existed. rebase = rebase the branch onto origin/<base> and publish with --force-with-lease, never a merge of the base into the branch. Rebase rewrites history, so the agent still asks for it unless the git-history-discipline rule already authorises the rewrite (the user asked this turn, an unrevoked standing instruction, or a pull --rebase the user started); this key decides which operation is proposed, never whether one is authorised.'),
+    }).default({}),
     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.'),
     }),
@@ -140,18 +138,21 @@ export const settingsSchema = z.object({
             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({
-        skip_pre_run_gate: z.boolean().default(true).describe('Skip the /roadmap:process-* pre-run confirmation gate. true (default) starts processing immediately and surfaces the resolved config inline; false shows the numbered-options gate and waits. A genuine "which roadmap?" ambiguity always prompts regardless.'),
         quality_cadence: qualityCadence.default('per_phase').describe('When the agent runs the full quality / test suite during /roadmap:process-* runs. per_phase = after each phase boundary (default since 2026-09-13 — end_of_roadmap lets errors compound across phases, which is expensive in a multi-phase autonomous run nobody is watching). end_of_roadmap = once, after the last step (fastest). per_step = after every single step (slowest, highest confidence).'),
-        dashboard_regen_cadence: regenCadence.default('every_5_steps').describe('How often the agent regenerates agents/roadmaps/dashboard.md during a roadmap run. every_5_steps = batch the regen (default). per_step = after every step (freshest dashboard, highest subprocess overhead). phase_boundary = only at phase edges. A rename, phase add, or archive always regenerates immediately regardless.'),
         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.'),
         gate_budget: z.object({
-            max_cost_per_run_usd: z.number().min(0).default(5).describe('Per-run USD ceiling for a CLASS-1 roadmap blocker executed via `agent-config gates --execute`. A class-1 entry whose **Budget:** field states a larger figure renders its consent line instead of running. Bounds the size of an authorised spend; never supplies the authorisation — `--confirm` is still required on every class-1 run.'),
-            max_cost_per_rolling_7d_usd: z.number().min(0).default(25).describe('Rolling 7-day USD ceiling for class-1 gate execution, summed from the append-only receipt ledger at agents/runtime/state/gate-budget-ledger.jsonl. A run whose estimate would cross it renders instead of running. A per-run cap alone bounds one mistake, not a week of them, which is why option (a) of b-gate-budget-preauth carries two numbers.'),
-        }).default({ max_cost_per_run_usd: 5, max_cost_per_rolling_7d_usd: 25 }),
+            // `.min(0)` is kept deliberately, at a known cost: the settings-
+            // reference generator renders a constrained nullable number as
+            // type `unknown` rather than `number,null` (it reads `node.type`,
+            // which a constrained nullable emits as an `anyOf` instead).
+            // Eight keys already render that way. Dropping the constraint
+            // would buy a nicer doc cell by letting a negative USD ceiling
+            // into the schema, and a cap that refuses everything is a worse
+            // outcome than an uninformative table cell.
+            max_cost_per_run_usd: z.number().min(0).nullable().default(null).describe('Per-run USD ceiling for a CLASS-1 roadmap blocker executed via `agent-config gates --execute`. A class-1 entry whose **Budget:** field states a larger figure renders its consent line instead of running. null (default) = no per-run ceiling, per ADR-279: a spend bound applies only where one was set, and the absence of a bound is not a refusal. Bounds the size of an authorised spend; never supplies the authorisation — `--confirm` is still required on every class-1 run, set or unset.'),
+            max_cost_per_rolling_7d_usd: z.number().min(0).nullable().default(null).describe('Rolling 7-day USD ceiling for class-1 gate execution, summed from the append-only receipt ledger at agents/runtime/state/gate-budget-ledger.jsonl. A run whose estimate would cross it renders instead of running. null (default) = no rolling ceiling, per ADR-279. A per-run cap alone bounds one mistake, not a week of them, which is why option (a) of b-gate-budget-preauth carries two numbers — but each cap now bounds on its own, so setting one and leaving the other null is supported.'),
+        }).default({ max_cost_per_run_usd: null, max_cost_per_rolling_7d_usd: null }),
     }),
     planning: z.object({
         closure_pass: z.boolean().default(true).describe('Gate C — plan-closure pass. true (default) = a plan-artifact ask (/roadmap:create, roadmap-writing, /feature:plan, /feature:roadmap, /roadmap:materialize, /implement-ticket, /jira-ticket, /analyze:inbox, /analyze:roadmap-repos) ends in a closure pass (/challenge-me closure): every foreseeable decision is closed at the lowest rung that owns it and written into the roadmap\'s "## Decisions" table, so a long run never meets a question planning could have closed. false = inert, plan asks author directly. An explicit user bypass always wins for that turn and is counted as a bypass rather than as an absent closure.'),
@@ -190,53 +191,24 @@ export const settingsSchema = z.object({
         fidelity_mode: 'strict',
         approximation: { enabled: false, tolerance: { color: null, length: null } },
     }),
-    consistency: z.object({
-        cross_source: crossSourceMode.default('on').describe('Consumed by the cross-source-consistency rule. When the agent works from multiple sources (ticket text, an attached image/mockup, the spec, the codebase) it checks them against each other and asks before proceeding on a discrepancy — instead of silently guessing. on (default) = surface every real cross-source contradiction / silent-scope-expansion as one question; auto = surface only high-confidence contradictions, state low-confidence as an assumption; off = no cross-source checking.'),
-    }).default({ cross_source: 'on' }),
+    code_graph: z.object({
+        consumer_index_paths: z.array(z.string()).default([]).describe("Extra project-relative paths where THIS project keeps a code-graph index another tool wrote. The built-in list is deliberately vendor-neutral (graph.json, code-graph.json, .code-graph/graph.json) and names no tool, so a tool that writes its index elsewhere is named here rather than waited for. A graph found this way LOADS and answers query and explain with every edge tagged read-from-elsewhere; the gate verbs (impact, untested, dead) refuse a graph made only of such edges and say so, because an empty answer from a gate must not read as 'nothing found' when it means 'nothing trusted'. Absolute paths and paths escaping the project root are ignored."),
+    }).default({}),
     screenshots: z.object({
         identity_allowlist: z.array(z.string()).default([]).describe("Consumed by the doc-screenshot-hygiene rule and screenshot-hygiene skill. Public identity tokens SAFE to show unredacted in a documentation screenshot — the maintainer's own public handles plus well-known fake-data tokens. Not a general fake-data dictionary and not identity-resolution: everything not listed is treated as sensitive by default, and a public handle co-located with a real name does not whitelist the real name. Default [] = nothing auto-allowed."),
         forbid_terminal_capture: z.boolean().default(true).describe('Consumed by the doc-screenshot-hygiene rule. true (default) = terminal/CLI/IDE screenshots are forbidden (highest leak vector: absolute local paths, env tokens); use text code blocks with text redaction instead. false = allowed, still subject to the data-bearing human gate.'),
         data_bearing_gate: z.enum(['on', 'off']).default('on').describe('Consumed by the doc-screenshot-hygiene rule. on (default) = a data-bearing screenshot embed is gated behind this-turn human confirmation; uncertain/unresolved regions redact-or-refuse, never ship-and-hope; illustrative/no-data screenshots may embed with a stated justification. off = no data-bearing gate (the anonymization taxonomy still applies).'),
     }).default({ identity_allowlist: [], forbid_terminal_capture: true, data_bearing_gate: 'on' }),
-    telegraph: z.object({
-        speak: z.boolean().default(false).describe('Whether the telegraph-speak rule ships at all. false (default) = DORMANT: compile_router omits the rule from dist/router.json entirely, so its body never reaches a host. This is the only lever that stops the cost. Set true only after an output-side bench clears the kill-criterion bar (docs/adrs/telegraph/0002).'),
-    }).default({ speak: false }),
-    tokens: z.object({
-        rich_skills: richSkillsMode.default('on').describe('Whether skills marked token_budget_class: rich may load in full (exempt from telegraph-speak + thin-projector trimming), consumed by the token-budget-discipline rule. on = allowed (default); off = fall back to standard condensed behavior; ask = surface an estimated token delta (tokens, not dollars) and ask once per session before loading.'),
-    }).default({ rich_skills: 'on' }),
     verbosity: z.object({
-        intent_announcements: z.boolean().default(false).describe('Intent narration before tool batches ("Let me check X…"). Only honored when personal.play_by_play is ALSO true (the direct-answers narration carve-out requires both). false (default) = act and emit the result.'),
-        preview_artifacts: z.boolean().default(false).describe('Show generated commit messages, PR titles/bodies, branch names before acting. false (default) = use generated content directly (/commit terse path).'),
-        routine_confirmations: z.boolean().default(false).describe('Confirmation prompts for routine workflow steps with one obvious answer. Iron-Law gates (commit-policy, scope-control git-ops, Hard Floor) ALWAYS ask regardless.'),
         offer_council_in_delivery: z.boolean().default(false).describe('Offer "run AI Council on this?" inside delivery commands (/feature-plan, /review-changes, /roadmap-create). Council commands themselves are unaffected.'),
-        post_action_reports: z.enum(['off', 'minimal', 'full']).default('minimal').describe('Status blocks after a successful action. off = errors only; minimal (default) = one-line confirmation; full = bullet list.'),
-    }).default({
-        intent_announcements: false,
-        preview_artifacts: false,
-        routine_confirmations: false,
-        offer_council_in_delivery: false,
-        post_action_reports: 'minimal',
-    }),
+    }).default({ offer_council_in_delivery: false }),
     code_style: z.object({
         docblocks: z.enum(['minimal', 'full']).default('minimal').describe('Consumed by the code-comment-discipline rule. minimal (default) = no signature-mirroring docblocks; docblocks only for machine-relevant precision (generics, array shapes) or genuine why-context. full = the exported public surface of a library package may carry one-line summary docblocks; the redundancy ban still holds.'),
     }).default({ docblocks: 'minimal' }),
     reasoning: z.object({
         enabled: z.boolean().default(true).describe('Master switch for the Reasoning Discipline Protocol (RDP). false = the whole layer is inert (zero overhead).'),
-        auto_gate: z.boolean().default(true).describe('Engage the discipline only where it pays, using table-free signals (task triviality + agent-self-assessed host reasoning strength; no runtime model->band lookup, per ADR-035). false = gate on task-signal + the component toggles only.'),
-        components: z.object({
-            orchestrator: z.boolean().default(true).describe('Sequence the reasoning chain (ground->intent->notes->gather->audit->verify) as one system; the single coordination point.'),
-            notes_first: z.boolean().default(true).describe('Keep hypotheses/predictions/decisions in session notes; the response carries conclusions + evidence only.'),
-            grounding: z.boolean().default(true).describe('Explore the environment / close info-gaps before designing.'),
-            intent: z.boolean().default(true).describe('Infer the underlying goal before solving the literal ask (standard host only).'),
-            complexity_first: z.boolean().default(true).describe('Risk-first: resolve the load-bearing unknown before the easy parts (RDP derivation, not a Fable-documented behavior).'),
-            verifier_default: z.boolean().default(true).describe('Run a fresh-context verifier on the structural-complexity gate (branching/constraints/stateful/irreversible + token floor).'),
-            prediction_tracking: z.boolean().default(true).describe('Log prediction + confidence + outcome + lesson (calibration loop).'),
-            decision_ledger: z.boolean().default(true).describe('Log decision + alternatives + reason + revisit-if; escalates to decision-record/ADR when durable.'),
-            uncertainty_budget: z.boolean().default(true).describe('Per-dimension uncertainty score that feeds adaptive effort.'),
-        }).default({}),
     }).default({}),
     subagents: z.object({
-        downshift: z.boolean().default(true).describe('Route delegable sub-tasks to the lowest-capable model tier (cost + speed via model downshift). false = every subagent runs on the session tier.'),
         quota_arbitrage: z.boolean().default(true).describe('Prefer a separate quota-pool model for delegable sub-tasks where the host manifest reports one. Optional bonus only — identical behaviour (minus the quota win) where unsupported. Never load-bearing.'),
         model_map: z.object({
             lite: z.string().default('').describe('Model alias for lite-tier sub-tasks. Empty = the tier runtime default.'),
@@ -246,7 +218,7 @@ export const settingsSchema = 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.'),
         model_ceiling: z.string().default('').describe('Session-wide model CEILING for subagents (spend cap). Empty (default) = no ceiling. When set, suite-owned CLI spawn wrappers export CLAUDE_CODE_SUBAGENT_MODEL to the sessions they launch. Class C: a human sets it; the agent never writes or infers one.'),
-        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.'),
+        max_parallel: z.number().int().min(1).default(3).describe('Limit on subagents running in parallel during /do-in-parallel, /do-competitively, and /judge runs — a value the model reads from settings; no code counts spawns against it. Raise for faster fan-out, lower if you hit rate limits or want lower token spend.'),
         adversarial_council: z.enum(['off', 'ask', 'on']).default('off').describe('Opt-in adversarial-verification-council mode (subagent-orchestration Mode 9, ADR-122). off (default) = never runs; ask = offer it on an explicit high-risk change; on = auto-run on high-risk changes. Advisory only — a panel of distinct-model skeptics red-teams a real change for defect FINDING coverage and NEVER auto-gates it (Hard Floor). Stays default-off until the adversarial-council-finding-coverage claim is backed.'),
     }),
     // `worktrees.mode` was DELETED (ADR-229). Worktree creation is
@@ -256,12 +228,11 @@ export const settingsSchema = z.object({
         model: z.string().default('auto').describe("Model handed to the codex CLI. 'auto' (default) = pass no --model flag so the CLI's own default applies — tracks the subscription's current strongest model instead of pinning a stale ID. Any other value passes through verbatim as `--model <value>`."),
         allow_delegate: z.boolean().default(false).describe('Second opt-in for the only wrapper that delegates write access (/team:delegate). false (default) = delegate refuses even when /team itself is available. Availability (codex CLI installed + authenticated) is necessary but not sufficient — this key must ALSO be true before delegation is reachable.'),
         max_calls_per_day: z.number().int().min(0).default(50).describe('Per-day cap on team calls, read against the EXISTING cli_call_budget openai bucket (~/.event4u/agent-config/cli-calls.json, daily UTC reset) — one subscription, one counter, never a parallel count. 0 = block all team calls.'),
-        suppress_setup_hint: z.boolean().default(false).describe('Suppress the one-line wizard/init recommendation to set up the codex plugin on Claude-Code hosts. Cosmetic only — never changes behavior.'),
         review_gate: z.object({
             managed: z.boolean().default(false).describe("Managed governance of the codex plugin's Stop-hook Review Gate (road-to-team-mode Phase 4). false (default) = byte-identical pre-Phase-4 behavior: no counting, no circuit breaker. true = count consecutive BLOCK verdicts per session and trip the circuit breaker at max_consecutive_blocks."),
             max_consecutive_blocks: z.number().int().min(1).default(3).describe('Circuit-breaker bound: after this many CONSECUTIVE BLOCK verdicts in one session, a visible notice is injected exactly once and the managed layer stops re-blocking — the user decides, never an infinite Claude↔Codex loop. An ALLOW verdict resets the counter. Positive integer.'),
         }).default({ managed: false, max_consecutive_blocks: 3 }),
-    }).default({ model: 'auto', allow_delegate: false, max_calls_per_day: 50, suppress_setup_hint: false, review_gate: { managed: false, max_consecutive_blocks: 3 } }),
+    }).default({ model: 'auto', allow_delegate: false, max_calls_per_day: 50, review_gate: { managed: false, max_consecutive_blocks: 3 } }),
     emergency: z.object({
         orchestration_halt: z.boolean().default(false).describe('The one audited incident switch over the always-on orchestration stack (subagents, council, team). NOT an activation gate: false (default) = the stack runs normally. true = halted; arming requires no ceremony. Disarming (returning to false) requires orchestration_halt_justification to be a non-empty string. Both transitions emit one telemetry line.'),
         orchestration_halt_justification: z.string().default('').describe('Required non-empty before orchestration_halt may return to false. Ignored while arming the halt.'),
@@ -270,21 +241,13 @@ export const settingsSchema = 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({
-        auto_detect: z.enum(['enabled', 'warn', 'disabled']).default('enabled').describe('Global kill-switch for orchestrator auto-detection (6.1.0 non-interactive-contract). enabled (default) = /judge, /fix, /analytics, /tests, /override auto-detect their sub-command per a confidence-tiered table; warn = detect but always confirm before routing; disabled = never auto-detect (always show the menu interactively, require an explicit sub-command in CI). Per-orchestrator override: auto_detect:false in front-matter. Per-invocation: --no-auto-detect.'),
         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.'),
             detail_level: z.enum(['min', 'med', 'max']).default('min').describe('Verbosity tier for the generated PR description body. min (default) = title + 2-3 sentence what/why/impact + linked ticket (token-frugal); med = min + grouped changes + tests note; max = med + how-to-test + edge cases + reviewer guidance. Critical info (breaking changes, migrations, security, rollback) is ALWAYS included at every tier — the tier governs explanatory depth, never whether a critical callout appears.'),
-            api_examples: z.boolean().default(true).describe('JSON request/response examples for API-endpoint changes. true (default) = include a fenced example ONLY when grounded in a real source (response DTO/resource, OpenAPI/schema, test fixture, or an actual probe); no grounded source → a one-line pointer, never an invented example. false = never add API examples.'),
             screenshots: z.boolean().default(false).describe('Screenshots for frontend changes. false (default) = never attempt. true = attempt when the host has browser/preview tooling and the diff touches a frontend surface; capability-gated (emits a one-line note and leaves the placeholder when tooling is absent, never fails or blocks the PR). Before/after + changed-region highlighting is best-effort.'),
-            ui_paths: z.array(z.string()).default([]).describe('Optional glob list that makes frontend detection explicit instead of heuristic (e.g. ["resources/views/**", "src/pages/**"]). Empty (default) = a light path/extension heuristic that fails open (no false enrichment when the surface is ambiguous).'),
-            api_paths: z.array(z.string()).default([]).describe('Optional glob list that makes API-endpoint detection explicit instead of heuristic (e.g. ["app/Http/Controllers/Api/**", "src/pages/api/**"]). Empty (default) = a light path/extension heuristic that fails open.'),
         }),
     }),
     continuity: z.object({
@@ -292,8 +255,6 @@ export const settingsSchema = z.object({
         run_checkpoints: z.enum(['on', 'off']).default('on').describe('Deterministic run-checkpoint production at session end (road-to-continuity-writer-activation Phase 1.4). on (default) = a session above the recycle threshold and inside a running roadmap contract leaves agents/runtime/state/checkpoints/<run>.json, so a killed run resumes from a derived checkpoint rather than from bookkeeping. off = no checkpoint; continuity writing, the recycle advisory and the context-fill surface are unaffected. Default ON because it is the behavior the tree already had — the switch exists to make the three session-end handlers independently disableable, not to change what ships.'),
     }),
     memory: z.object({
-        cadence: memoryCadence.default('always').describe('Cadence of the 🧠 memory-visibility line after a memory-consulting step. always (default) = show whenever a memory type was asked; auto = show only when 3+ types were consulted (less noise); never = suppress. Distinct from rule_loading_tier — owns its own key since the 2026-06-01 untangle.'),
-        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.'),
         session_index: z.enum(['on', 'off']).default('off').describe('Opt-in compact memory index at session start (road-to-memory-retrieval-economy P5). on = inject a compact id + title + ~tokens index of curated entries (hard cap 30 rows, bodies never included) through the hot-context hook; the agent fetches full entries via memory_get on demand. off (default) = no injection — the ship-criterion (measured hit-rate gain) is unproven, so off unless proven.'),
         learn_on_session_end: z.boolean().default(false).describe('session_end learning-sidecar aggregation (road-to-reachable-code-memory P4). true = the session_end hook aggregates agents/memory/intake/*.jsonl through the learning sidecar into the gitignored .agent-learning.json + LESSONS.md (local-only, 2 s budget, fail-open; promotion stays human via /memory:propose). false (default, council 2026-07-27) = no-op; the flip is proposed only after the 30-day dogfood shows non-trivial signal AND session-end p95 < 2 s.'),
@@ -302,23 +263,15 @@ export const settingsSchema = z.object({
         global_sharing: z.object({
             enabled: z.boolean().default(true).describe('Master switch for the file-first global knowledge-card store (ADR-100; default-ON per ADR-119, the validated bounded-downside flip superseding ADR-103 — write-time redaction incl. hidden-unicode hardening, narrowest tier default, pre-registered demotion trigger). User-global setting — keep in ~/.event4u/agent-config/agent-settings.yml. false fully no-ops the layer (single-key revert); project-local cards (v1) are unaffected.'),
             allowed_tiers: z.array(z.string()).default(['public']).describe('Origin tiers auto-eligible to cross a project boundary. proprietary is manual-only regardless (the gate hard-codes it), so an in-house schema never auto-shares.'),
-            redaction: z.object({
-                enabled: z.boolean().default(true).describe('Run the privacy-floor + source-confidentiality scan before any card goes global.'),
-                halt_on_trigger: z.boolean().default(true).describe('Halt-and-surface on a confidential-pattern hit; never silent-share, never auto-rewrite.'),
-            }).default({}),
-            auto_promote_threshold: z.number().int().min(1).default(2).describe('Distinct-repo count at which a public/vendor card triggers a promotion suggestion (never a silent write).'),
-            freshness: z.object({
-                hypothesis_after_days: z.number().int().min(0).default(90).describe('A global card older than this is lead-only (positive structure must be re-confirmed before use).'),
-                stale_after_days: z.number().int().min(0).default(180).describe('A global card older than this is skipped until re-verified.'),
-            }).default({}),
         }).default({}),
     }).default({}),
     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.'),
         }),
+        verify_before_complete: z.object({
+            touched_file_quality: z.enum(['off', 'shadow', 'warn']).default('off').describe("Stop-slot pass that runs the project's OWN quality commands — the ones resolve_toolchain() already reports — over the files this turn edited. Default off. `shadow` records a per-run result and emits nothing; `warn` adds ONE advisory line of at most 200 bytes. Never blocks and never counts as verification: a command recorded here never reaches _lib/verification_command.ts, so a clean eslint run cannot let a turn claim it verified anything. A writing command runs only in its check form (pint --test) or not at all, and a command with no per-file form is skipped rather than run project-wide at every stop."),
+        }).default({}),
         injection_scan: z.object({
             enabled: z.boolean().default(false).describe('PostToolUse prompt-injection scanner (road-to-security-pillar.md P3.2). Default off. When on, scans tool output (file reads, web fetches, MCP responses) for injection signatures and WARNS in context (never blocks). Runtime backstop on top of the always-on untrusted-input-defense rule; detection is probabilistic.'),
         }).default({}),
@@ -348,23 +301,18 @@ export const settingsSchema = z.object({
         // fires is decided by each detector's own trigger conditions, not by a
         // flag. A leftover `hooks.turn_end_gate.*` block from an older install
         // warns once on stderr and is ignored — see REMOVED_KEYS in
-        // `src/scripts/_lib/agent_settings.ts`.
+        // `src/scripts/_lib/settings_removed_keys.ts`.
     }),
     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.'),
+        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, the engine stops (fail-safe). Default 30s; raise for slow human review, 0 = wait forever.'),
     }),
     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.'),
-    }),
     legal_review_prep: z.object({
         acknowledged: z.boolean().default(false).describe('I understand the legal-review-prep pack provides templates and general information ONLY — it is NOT legal advice, creates no attorney-client relationship, and never replaces a licensed lawyer. Individual cases require an attorney. The pack stays inactive until this is checked.'),
         require_council: z.boolean().default(true).describe('Gate legal work-product behind a multi-model AI-council / deep-research pass (defense-in-depth: documented multi-stage review + audit trail; fail-closed when no council is configured). Leave on for the safest posture. Turning it off lets single-model legal output through — not recommended for a high-risk pack.'),

package/dist/shared/skillRanking.js

@@ -24,10 +24,13 @@
  * `score_skill_relevance` CLI's argparse-parity suite is the check that the move
  * changed nothing.
  *
- * THE ONE ADDITION is `triggerTerms`, off by default. Phase 3.1 of the same
- * roadmap indexes `triggers.keyword` / `triggers.phrase` text; it is an opt-in
- * parameter rather than a second function so the two rankers can be measured
- * against each other on one corpus.
+ * THE ADDITIONS ARE ALL OFF BY DEFAULT and live in one {@link RankOptions}
+ * object: three that widen the indexed TERM SOURCE (trigger prose, the skill's
+ * own `## When to use` section, the body's headings) and one that changes the
+ * WEIGHTING (inverse document frequency over the catalogue). They are opt-in
+ * parameters rather than separate functions so two configurations can be
+ * measured against each other on one corpus without becoming two rankers. With
+ * every flag off the arithmetic is the ported one, unchanged.
  *
  * Pure — no imports, no I/O, no clock.
  */
@@ -113,23 +116,85 @@ export function skillTerms(skill, opts = {}) {
     const parts = [skill.name, skill.description];
     if (opts.includeTriggers && skill.triggerText)
         parts.push(...skill.triggerText);
+    if (opts.includeWhenToUse && skill.whenToUseText)
+        parts.push(skill.whenToUseText);
+    if (opts.includeHeadings && skill.headingText)
+        parts.push(...skill.headingText);
     return tokenize(parts.join(' '));
 }
+/** True when `opts` turns on at least one term source beyond name + description. */
+export function widensTermSource(opts) {
+    return Boolean(opts.includeTriggers || opts.includeWhenToUse || opts.includeHeadings);
+}
+/**
+ * @param termSets the per-skill term sets, in the same order as `skills`.
+ *   Required rather than derived, so the catalogue is tokenized ONCE per call
+ *   instead of once here and again at the scoring loop. Tokenizing ~300 skills
+ *   twice per prompt is invisible next to re-reading them from disk, which is
+ *   exactly why it would have stayed invisible.
+ */
+export function buildTermStats(skills, termSets) {
+    const df = new Map();
+    for (const terms of termSets) {
+        for (const t of terms)
+            df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    return { df, skills: skills.length };
+}
+/**
+ * The weight one matched term carries.
+ *
+ * `ln(1 + skills / (1 + df))`, the smoothed textbook form: a term on every
+ * skill tends to zero, a term on one skill carries the most. Unknown terms are
+ * treated as df 0 — a task term no skill indexes cannot be matched anyway, so
+ * its weight only affects the denominator, where counting it fully is right:
+ * failing to cover a rare term should cost more than failing to cover a common
+ * one.
+ */
+export function idf(term, stats) {
+    return Math.log(1 + stats.skills / (1 + (stats.df.get(term) ?? 0)));
+}
 /**
  * The score. `taskTerms` is `tokenize(task)`; `terms` is `skillTerms(skill)`.
  *
  * Both are passed in rather than derived here so a caller ranking N skills
  * tokenizes the task once and each skill once, which is what makes this usable
- * on a per-prompt hook path.
+ * on a per-prompt hook path. `opts` and `stats` are optional and, with them
+ * absent or every flag off, the arithmetic is exactly the Python-parity one.
  */
-export function scoreSkill(taskTerms, skill, terms) {
+export function scoreSkill(taskTerms, skill, terms, opts = {}, stats) {
+    return roundHalfToEven(rawSkillScore(taskTerms, skill, terms, opts, stats));
+}
+/**
+ * The score before `roundHalfToEven` — what {@link scoreSkill} rounds. Exposed
+ * only so `tieBreakUnrounded` can order a block of equal integers by it.
+ */
+export function rawSkillScore(taskTerms, skill, terms, opts = {}, stats) {
+    if (opts.idfWeighting && !stats) {
+        throw new Error('scoreSkill: idfWeighting is set but no TermStats was passed — scoring unweighted here ' +
+            'would publish a baseline number under the idf label. Build stats with buildTermStats.');
+    }
     if (taskTerms.size === 0)
         return 0;
-    let inter = 0;
-    for (const t of taskTerms)
-        if (terms.has(t))
-            inter++;
-    const overlap = inter / Math.max(taskTerms.size, 1);
+    let overlap;
+    if (opts.idfWeighting && stats) {
+        let hit = 0;
+        let total = 0;
+        for (const t of taskTerms) {
+            const w = idf(t, stats);
+            total += w;
+            if (terms.has(t))
+                hit += w;
+        }
+        overlap = total > 0 ? hit / total : 0;
+    }
+    else {
+        let inter = 0;
+        for (const t of taskTerms)
+            if (terms.has(t))
+                inter++;
+        overlap = inter / Math.max(taskTerms.size, 1);
+    }
     let personaHit = 0;
     const taskLower = [...taskTerms].join(' ');
     for (const persona of skill.personas ?? []) {
@@ -139,7 +204,7 @@ export function scoreSkill(taskTerms, skill, terms) {
             break;
         }
     }
-    return roundHalfToEven(overlap * 70 + personaHit * 30);
+    return overlap * 70 + personaHit * 30;
 }
 /**
  * Rank an in-memory skill set. Zero scores are dropped; ties break on name, so
@@ -147,13 +212,35 @@ export function scoreSkill(taskTerms, skill, terms) {
  */
 export function rankSkills(task, skills, opts = {}) {
     const taskTerms = tokenize(task);
+    const termSets = skills.map((s) => skillTerms(s, opts));
+    const stats = opts.idfWeighting ? buildTermStats(skills, termSets) : undefined;
     const rows = [];
-    for (const skill of skills) {
-        const score = scoreSkill(taskTerms, skill, skillTerms(skill, opts));
-        if (score > 0)
+    const raw = new Map();
+    for (let i = 0; i < skills.length; i += 1) {
+        const skill = skills[i];
+        const unrounded = rawSkillScore(taskTerms, skill, termSets[i], opts, stats);
+        const score = roundHalfToEven(unrounded);
+        if (score > 0) {
             rows.push({ name: skill.name, score, personas: [...(skill.personas ?? [])] });
+            raw.set(skill.name, unrounded);
+        }
     }
-    rows.sort((a, b) => (b.score - a.score) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    rows.sort((a, b) => compareRanked(a.name, a.score, b.name, b.score, opts, raw));
     return rows;
 }
+/**
+ * The ranking order: score descending, then — only under `tieBreakUnrounded` —
+ * the unrounded score descending, then the name. One comparator for both
+ * rankers, so the flag cannot mean two orders in two places.
+ */
+export function compareRanked(aName, aScore, bName, bScore, opts, raw) {
+    if (bScore !== aScore)
+        return bScore - aScore;
+    if (opts.tieBreakUnrounded) {
+        const d = (raw.get(bName) ?? 0) - (raw.get(aName) ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return aName < bName ? -1 : aName > bName ? 1 : 0;
+}
 //# sourceMappingURL=skillRanking.js.map