@event4u/agent-config 5.10.1 → 6.1.0

package/src/config/agent-settings.template.yml

@@ -0,0 +1,674 @@
+# Agent Settings
+# This file is generated by scripts/install.py from
+# config/agent-settings.template.yml. It holds personal and project-wide
+# preferences. Run /onboard for first-run setup; for later edits, change
+# values here directly or ask the agent (it follows the merge rules in
+# .augment/guidelines/agent-infra/layered-settings.md).
+
+# --- Agent config version pin ---
+#
+# Exact semver of the @event4u/agent-config release this project is
+# pinned to. Used by `npx @event4u/agent-config <cmd>` to re-exec at
+# the pinned version when the developer's local resolution differs.
+# Empty string = unpinned (resolver picks the latest release; only safe
+# for greenfield projects). Ranges (^, ~, >=) are NOT supported — the
+# pin replaces lockfile determinism, so it must be exact.
+# See docs/customization.md § "Agent config version pin" and
+# docs/architecture.md § "npx-only distribution + version-pin governance".
+agent_config_version: ""
+
+# --- Profile (experience) ---
+#
+# Which experience you run. This is the FIRST question the setup wizard
+# asks ("which experience?") — it selects your default skill / command
+# surface, README entry-path, and persona pre-selection.
+#   Valid ids: developer | content_creator | founder | agency | finance | ops
+# See docs/contracts/profile-system.md and ADR-010.
+#
+# In 6.0.0-A this records the choice only — it does NOT yet narrow what
+# gets projected into .claude/ .cursor/ .augment/. Pack-scoped surfacing
+# (projection-time filtering, ADR-040) ships in 6.0.0-B behind a staged,
+# opt-in rollout (legacy-all stays the default until evidence confirms
+# the "too many surfaces" hypothesis). Switch experiences later with
+# `agent-config use --profile=<id>`.
+profile:
+  id: developer
+
+# --- Pack-scoped projection (ADR-040, 6.0.0-B) ---
+#
+# Whether the per-tool projector writes EVERY artefact into the host-tool
+# trees (.claude/ .cursor/ .windsurf/) or only the active profile + packs'
+# artefacts. See docs/decisions/ADR-040 and docs/contracts/capability-packs.md.
+#
+# legacy-all = (DEFAULT, non-breaking) project the full surface, exactly as
+#              5.x did. An `npm update` to 6.0.0 changes nothing here.
+# scoped     = project only the active profile's `packs` unioned with the
+#              runtime.active_packs overlay, expanded over the `requires`
+#              graph. Opt in with `agent-config use --profile=<id>`.
+#
+# Scoping is opt-in by THIS key alone — never inferred from profile.id (every
+# install has `developer` by default). A failed scoped projection restores the
+# full tree. The committed plugin marketplace (.claude-plugin/) and the Augment
+# tree (.augment/) always project the full set in 6.0.0.
+projection:
+  mode: legacy-all
+
+# --- Cost profile ---
+#
+# Master switch that controls which rule tiers load each session.
+# See docs/customization.md for the authoritative description and
+# docs/contracts/rule-router.md for the kernel + router architecture.
+#
+# minimal  = kernel only (always-loaded Iron-Law floor, ≤ 26k chars).
+#            No router, no auto-rules. Lowest token footprint.
+# balanced = kernel + tier-1 auto-rules (default — current behaviour superset).
+# full     = kernel + tier-1 + tier-2 (everything, highest token cost).
+# custom   = ignore profile — every matrix value must be set explicitly.
+rule_loading_tier: __RULE_LOADING_TIER__
+
+# --- Lean projection (experimental, opt-in) ---
+#
+# How the per-tool projector emits the rule layer. See
+# docs/contracts/rule-router.md § Kill-switch.
+#
+# eager-all = every rule body inlined into every projection (DEFAULT,
+#             today's behaviour). Safe — bodies are always in context.
+# thin      = kernel rules full-bodied + non-kernel rules as
+#             router-resolved pointers (the agent loads the body on
+#             trigger-match). Measured ~45k GPT-tok lighter per session
+#             (77% of the rule layer). EXPERIMENTAL: a thin projection
+#             only holds behaviour if the pointer is resolved on match —
+#             validate with `task bench:ab:live` before flipping, and
+#             keep `task trigger-coverage` at 100%. One-flip revert:
+#             set eager-all + `task generate-tools`.
+lean_projection:
+  mode: eager-all
+
+# --- Cost tracking + budget enforcement ---
+#
+# USD budgets evaluated against `agents/cost-tracking/sessions.jsonl` by
+# `scripts/cost/budget.mjs`. Empty / 0 = unbudgeted (no enforcement,
+# `cost:check` reports spend only). See docs/contracts/cost-enforcement.md
+# for the full contract (tier ladder, hook surface, bypass mechanism).
+cost:
+  budgets:
+    # Daily USD ceiling (rolling 24h). 0 / null = no daily budget.
+    daily: 0
+    # Weekly USD ceiling (rolling 7d). 0 / null = no weekly budget.
+    weekly: 0
+    # Monthly USD ceiling (rolling 30d). 0 / null = no monthly budget.
+    monthly: 0
+  # Enforcement mode at the HARD_STOP tier (100% utilization):
+  #   advisory  = dashboards and `cost:check` show the breach; agent
+  #               keeps working. Default. Safe for greenfield projects.
+  #   hard-stop = preflight hook (scripts/cost/preflight.mjs) exits
+  #               non-zero on HARD_STOP; CI / shell wrappers refuse to
+  #               start the turn until the budget is raised or reset.
+  enforcement: advisory
+
+# --- Per-skill model auto-switch (ADR-035) ---
+# Skills declare a vendor-neutral `model_tier` (lite|medium|high); the generator
+# maps it to a native Claude model (high→opus, medium→sonnet, lite→haiku).
+#   suggest = (default) never emit a native Claude `model:` key; the
+#             model-recommendation rule names the tier as a one-question
+#             suggestion on every surface — never silently overrides /model.
+#   auto    = render a native Claude `model:` into lite/medium/high-tier skills
+#             (Claude switches for that turn, reverts next prompt); suggest
+#             on surfaces without a native override.
+#   off     = inert — no native key, no suggestion.
+model:
+  auto_switch: suggest
+
+# --- Personal preferences ---
+personal:
+  # IDE to use for opening files (code, phpstorm, cursor, …)
+  # Empty = agent will not auto-open files; fill in once if you want that.
+  ide: ""
+
+  # Automatically open edited files in the IDE (true, false)
+  open_edited_files: false
+
+  # rtk (Rust Token Killer) installed for output filtering (true, false)
+  # Agent will auto-detect and ask once, then store the result
+  rtk_installed: false
+
+  # Minimal output mode (true, false)
+  # true  = short bullet points during work, concise summary at the end
+  # false = verbose explanations and reasoning
+  minimal_output: true
+
+  # Play-by-play mode (true, false)
+  # true  = briefly share intermediate findings as you go
+  # false = silently investigate, only report the conclusion
+  play_by_play: false
+
+  # Prefix PR comment replies with a bot icon 🤖 (true, false)
+  # Personal preference — each developer decides for themselves.
+  pr_comment_bot_icon: false
+
+  # Allow the agent to post unsolicited progress / status comments on
+  # an open PR (e.g. "CI fix iteration #2", "blocked on workflow scope").
+  # true  = agent may narrate work on the PR via `gh pr comment` etc.
+  # false = default; agent never auto-comments. 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.
+  pr_progress_comments: false
+
+  # Autonomous execution — suppress trivial workflow questions (on, off, auto)
+  # on   = act on the obvious next step; never ask "Step 2 or 3?", "should I commit?", etc.
+  # off  = ask trivial workflow questions (legacy behavior)
+  # auto = behaves like 'off' until the user says "arbeite selbstständig" / "work autonomously"
+  #        in the conversation, then switches to 'on' for the rest of the chat.
+  # Blocking decisions (security, scope expansion, push/merge/branch/PR) are NEVER suppressed.
+  # See rules/autonomous-execution.md for the full definition.
+  autonomy: auto
+
+  # Primary user-type for skill filtering (step-9 axis).
+  # Empty string ("") = no filter (legacy behavior — every skill surfaces).
+  # Set this via `bash scripts/install --user-type=<id>` or hand-edit later.
+  # Valid ids: consultant | creator | developer | finance | founder | gtm | ops
+  # See user-types/README.md for the per-id contract.
+  user_type: "__USER_TYPE__"
+
+# --- Project / team preferences ---
+project:
+  # Path to the PR template file (relative to project root)
+  pr_template: .github/pull_request_template.md
+
+  # Target repository for universal improvement PRs (e.g. org/agent-config)
+  upstream_repo: ""
+
+  # Branch prefix for improvement PRs
+  improvement_pr_branch_prefix: "improve/agent-"
+
+# --- GitHub integration ---
+github:
+  # API method for replying to PR review comments
+  # replies_endpoint      = POST /pulls/comments/{id}/replies (preferred)
+  # create_review_comment = POST /pulls/{number}/reviews (fallback)
+  # auto                  = detect on first use and update this setting
+  pr_reply_method: create_review_comment
+
+# --- Augment Code projection (.augment/) ---
+#
+# Controls how rule files are written into .augment/rules/ during
+# install (scripts/install.sh) and the package's own projection
+# (scripts/condense.py --project-augment).
+#
+# Augment Code historically does not load symlinked rule files, so the
+# default is to write each rule as a real copy. Flip the toggle to true
+# once Augment Code supports symlinked rules — symlinks keep the files
+# in sync without re-running install/sync, and remove a class of stale-
+# copy path bugs.
+augment:
+  # When true, .augment/rules/*.md are symlinked into dist/agent-src/rules/.
+  # When false (default) or missing, they are copied as real files.
+  rules_use_symlinks: false
+
+# --- Eloquent (Laravel) ---
+eloquent:
+  # Model property access style
+  # getters_setters  = strict typed getters/setters, getAttribute() only inside model
+  # get_attribute    = use getAttribute()/setAttribute() everywhere
+  # magic_properties = use $model->column_name (Laravel default)
+  access_style: getters_setters
+
+# --- Chat history (crash recovery) ---
+#
+# Persistent JSONL log at agents/runtime/.agent-chat-history (git-ignored).
+# Keeps a durable record of the conversation so a crashed or switched
+# agent session can be resumed. See scripts/chat_history.py for the API.
+chat_history:
+  # Log chat events to disk (true, false)
+  enabled: true
+
+  # Logging granularity
+  #   per_turn  = one entry per user↔agent turn (lightest)
+  #   per_phase = one entry per workflow phase
+  #   per_tool  = one entry per tool call (most verbose)
+  frequency: __CHAT_HISTORY_FREQUENCY__
+
+  # Max file size in KB before overflow handling kicks in (integer)
+  max_size_kb: __CHAT_HISTORY_MAX_SIZE_KB__
+
+  # Overflow behavior
+  #   rotate   = drop oldest entries to stay under max_size_kb
+  #   condense = mark for summarization on the next agent turn
+  on_overflow: __CHAT_HISTORY_ON_OVERFLOW__
+
+  # Per-entry-type text-length caps (chars). 0 = verbatim, no slice.
+  # N > 0 = collapse whitespace, slice to N chars, append " … [+K chars]"
+  # so the log self-reports truncation. Defaults match the hardcoded
+  # fallback in scripts/chat_history.py (DEFAULT_TEXT_LIMITS).
+  #   user  = your messages — full text by default (most valuable for crash recovery)
+  #   agent = agent replies — capped to keep the log compact under load
+  #   tool  = tool inputs/outputs — short by default; bump for noisy debugging
+  #   phase = workflow phase markers — short by default
+  text_limits:
+    user: 0
+    agent: 5000
+    tool: 200
+    phase: 200
+
+# --- Optional pipelines ---
+pipelines:
+  # Skill improvement pipeline (true, false)
+  # true  = after meaningful tasks, propose learning capture and improvements (default)
+  # false = silent, no post-task analysis
+  # Included by every rule_loading_tier except `custom`. Flip to false here if you
+  # want a silent agent; `custom` profile ignores this default entirely.
+  skill_improvement: true
+
+# --- Reasoning Discipline Protocol (RDP) ---
+#
+# Transplants the *operating discipline* of a frontier reasoning model
+# (ground -> intent -> notes -> gather -> audit -> verify) onto any host model.
+# It transfers discipline, never capability. Cost-gated so it only engages where
+# it pays. Rationale: docs/guidelines/agent-infra/frontier-reasoning-operating-profile.md
+reasoning:
+  # Master switch (true, false). false = the whole layer is inert (zero overhead).
+  enabled: true
+
+  # Auto benefit-gating (true, false). Engages only where it pays, using
+  # table-free signals (ADR-035 forbids any runtime model->band lookup table):
+  #   - task signal: trivial / short / fully-specified tasks -> OFF
+  #   - host reasoning strength (agent self-assessed, no maintained list): a
+  #     strong-reasoning host applies the discipline lightly / as suggestion;
+  #     a standard host applies it fully.
+  # One constraint-light scaffold ships; standard hosts expand it on request.
+  # false = gate on task-signal + toggles only (skip the self-assessment touch).
+  auto_gate: true
+
+  # Per-component switches. Each fires only when `enabled` AND the auto_gate test passes.
+  components:
+    orchestrator: true       # sequences the chain; the single coordination point
+    notes_first: true        # reasoning in session notes, never echoed in the response
+    grounding: true          # explore environment / close info-gaps before designing
+    intent: true             # infer the underlying goal before solving the literal ask
+    complexity_first: true   # risk-first: resolve the load-bearing unknown first (RDP derivation, not Fable-documented)
+    verifier_default: true   # fresh-context verifier on the structural-complexity gate (branching/constraints/stateful/irreversible + token floor)
+    prediction_tracking: true # log prediction + confidence + outcome + lesson (calibration loop)
+    decision_ledger: true    # log decision + alternatives + reason + revisit-if; escalates to decision-record/ADR when durable
+    uncertainty_budget: true # per-dimension uncertainty score; feeds adaptive effort
+
+# --- Roadmap execution ---
+#
+# Controls when /roadmap execute runs the project's quality pipeline
+# (the `task ci` / `make test` / `npm run check` style command).
+# Steps are ALWAYS marked `[x]` and the dashboard is ALWAYS regenerated
+# in the same response — that cadence is governed by `roadmap-progress-sync`
+# and is non-negotiable. This setting only governs *quality tool runs*.
+roadmap:
+  # Skip the /roadmap:process-* pre-run confirmation gate (true, false).
+  #   true  = default. The command name names the scope; a discoverable
+  #           single active roadmap (or a named one) starts the loop
+  #           immediately, resolved config surfaced inline so a wrong
+  #           pick can still be aborted mid-stream.
+  #   false = legacy. Shows the pre-run summary with numbered options
+  #           and waits. The gate is still shown regardless when the
+  #           roadmap is ambiguous or a scope / cadence conflict has no
+  #           sensible default. See rules/autonomous-execution.md.
+  skip_pre_run_gate: true
+
+  # When to run quality tools during /roadmap execute.
+  #   end_of_roadmap = once, before archiving the completed roadmap (default — fastest, fewest tokens)
+  #   per_phase      = once after every completed phase
+  #   per_step       = after every completed step (legacy verbose; highest token cost)
+  # Trade-off: end_of_roadmap saves tokens and time but lets errors compound
+  # across phases. Pick per_phase if the work is risky or unfamiliar.
+  # Iron Law `verify-before-complete` still applies — fresh quality output
+  # is mandatory before any "roadmap complete" claim regardless of cadence.
+  quality_cadence: end_of_roadmap
+
+  # Dashboard regen cadence inside autonomous runs (process-step /
+  # process-phase / process-full). Controls how often
+  # `./agent-config roadmap:progress` runs **between** steps in a
+  # single session. The dashboard is always regenerated at the start
+  # of the run, at every phase boundary, and at run end — this knob
+  # only affects the inter-step beat.
+  #
+  #   per_step         = legacy default: regen after every checkbox flip.
+  #                      Safest for crash recovery; highest subprocess
+  #                      overhead. Use when a session may be killed
+  #                      mid-roadmap and a fresh dashboard must always
+  #                      reflect the last-saved step.
+  #   every_5_steps    = batch flips, regen every 5 closed steps + at
+  #                      every phase boundary. Balanced cost/freshness
+  #                      for runs of 20–100 steps.
+  #   phase_boundary   = regen only at phase boundaries + run end.
+  #                      Cheapest for long roadmaps (100+ steps).
+  #                      The checkbox flip itself is still inline per
+  #                      Iron Law 2 — only the subprocess regen batches.
+  #
+  # `process-step` ignores this knob (single-step runs always regen
+  # at the end of the step). The Iron Law 1 mandate to regen on any
+  # file-shape touch (rename / phase add / archive) still fires
+  # immediately regardless of this setting.
+  dashboard_regen_cadence: per_step
+
+  # Visible-horizon framing in roadmap authoring (integer weeks, default 0).
+  # 0  = off (default). Time-boxed plate / horizon framing is forbidden:
+  #      no `## Horizon (N-week visible plate)` sections, no
+  #      "inside / outside the plate" phrasing, no `out-of-horizon` /
+  #      `out-of-plate` suffixes. Phase ordering and dependency gates
+  #      carry the deferral semantics. Enforced by
+  #      `task lint-roadmap-complexity`.
+  # > 0 = opt-in. Roadmaps may include a `## Horizon (N-week visible plate)`
+  #      section with that many weeks; the linter relaxes the plate-token
+  #      ban for files declaring the section. Pacing is still the user's
+  #      call — N is just the authoring window.
+  # 6 weeks proved too long for AI-paced work; the default is 0 so plans
+  # describe scope and ordering, not calendars. Flip to a positive integer
+  # only if your team genuinely commits work on a calendar plate.
+  horizon_weeks: 0
+
+# --- Quality / CI execution ---
+#
+# Controls whether the agent runs the project's quality pipeline
+# (`task ci`, `make test`, `npm run check`, PHPStan, ECS, Rector,
+# test suites) and whether it waits on remote CI after pushing.
+# Iron Law `verify-before-complete` still applies — when these
+# toggles suppress automatic runs, the agent MUST surface that and
+# ask before claiming completion rather than silently skipping
+# verification.
+quality:
+  # Run local quality / CI tasks and tests autonomously (true, false)
+  # true  = agent runs the quality pipeline whenever work is ready
+  #         for verification, without asking (default)
+  # false = agent asks before running quality tools / tests locally
+  #
+  # Carve-out (always runs regardless of this flag): when the change
+  # introduces a NEW CI gate, smoke test, or test file, the agent
+  # MUST execute it locally to prove the gate works. Without that
+  # execution the new gate is unverified evidence.
+  local_auto_run: true
+
+  # Wait for remote CI to finish on the PR / pipeline (true, false)
+  # true  = after push, poll GitHub check-runs / pipeline status and
+  #         report green / red before handing back
+  # false = push and hand back immediately; user inspects CI
+  #         themselves (default — saves agent runtime and tokens)
+  wait_for_remote_ci: false
+
+# --- Subagent orchestration ---
+#
+# Controls model selection and parallelism for subagent-based workflows
+# (/do-and-judge, /do-in-steps, /judge). Empty values fall back to the
+# runtime defaults described in .augment/contexts/subagent-configuration.md.
+subagents:
+  # Model for implementer subagents (empty = same tier as the session model)
+  implementer_model: ""
+
+  # Model for judge subagents
+  # (empty = one tier above implementer: opus if sonnet, sonnet if haiku)
+  judge_model: ""
+
+  # Maximum number of parallel subagent invocations
+  # Integer, default 3. Set to 1 to serialize. Hard cap enforced by runtime.
+  max_parallel: 3
+
+# --- Git worktrees ---
+#
+# Controls how the `using-git-worktrees` skill and `subagent-orchestration`
+# mode 6 (`do-in-worktrees`) behave. Mechanical layer on top of the
+# existing `scope-control` permission gate — narrows, never widens.
+worktrees:
+  # off | on | ask  (default: ask)
+  #
+  # ask = status quo. Skill asks before creating any worktree; mode 6 is
+  #       selectable when the chain shape warrants it. Matches the
+  #       behaviour required by `scope-control` and `autonomous-execution`.
+  # off = no autonomous worktree creation. Skill refuses; mode 6 falls
+  #       back to mode 3 (do-in-steps). Explicit user request in the
+  #       chat ("do this in a worktree", "use mode 6") overrides for
+  #       that single task — the setting suppresses *unprompted* usage,
+  #       not the tool itself.
+  # on  = standing permission. Skill skips the per-creation permission
+  #       ask; mode 6 may be picked without prompting. Iron-Law gates
+  #       (ignore-check, clean baseline) still apply.
+  mode: ask
+
+# --- AI Council (external second-opinion network) ---
+#
+# Configuration moved to `agents/.ai-council.yml` as of the Step-2
+# consolidation roadmap. Consumer projects opt in by copying the
+# reference file from the package (`agents/.ai-council.yml`) into their
+# own `agents/` tree and flipping `enabled: true` per provider.
+#
+# See `docs/contracts/ai-council-config.md` for the schema.
+
+# --- Onboarding ---
+#
+# Tracks whether the initial setup flow (/onboard) has been completed
+# for this developer on this project. When false, the onboarding-gate
+# rule prompts the user to run /onboard before starting normal work.
+# Missing entirely = legacy project (treated as onboarded).
+onboarding:
+  # Has the developer completed /onboard? (true, false)
+  # Set to true automatically by /onboard at the end. Flip to false if
+  # you want to re-run the flow.
+  onboarded: false
+
+# --- Command suggestion (numbered-options shortcut finder) ---
+#
+# When the user's free-form prompt matches an eligible slash command,
+# the agent surfaces a numbered-options block with the recommendation
+# plus an always-present "run as-is" option. The suggestion layer
+# never auto-executes — the user picks. See rules/command-suggestion-policy.md.
+commands:
+  # --- Orchestrator auto-detection (6.1.0 non-interactive-contract) ---
+  #
+  # Global kill-switch for the auto-detection layer on cluster
+  # orchestrators (/judge, /fix, /analytics, /tests, /override).
+  #   enabled  = (default) orchestrators auto-detect the sub-command per
+  #              their confidence-tiered detection table.
+  #   warn     = detect, but always confirm the detected sub-command
+  #              before routing (never silent, even on HIGH confidence).
+  #   disabled = never auto-detect; orchestrators always show the menu
+  #              (interactive) or require an explicit sub-command (CI).
+  # Per-orchestrator override: auto_detect: false in a command's
+  # front-matter. Per-invocation override: --no-auto-detect.
+  # See src/agent-src/contexts/execution/non-interactive-contract.md.
+  auto_detect: enabled
+
+  suggestion:
+    # Master switch (true, false). false = the layer is silent; explicit
+    # /commands still work as today.
+    enabled: true
+
+    # Minimum match score (0.0–1.0) before a suggestion surfaces.
+    # 0.6 = default; raise to 0.7 for stricter behaviour, lower to 0.5
+    # if too many useful suggestions are being suppressed.
+    confidence_floor: 0.6
+
+    # Cooldown in seconds between re-suggestions of the same
+    # (command, evidence) pair. Default 600s = 10m.
+    cooldown_seconds: 600
+
+    # Max number of command suggestions before the as-is option.
+    # The as-is option is always extra (so total = max_options + 1).
+    max_options: 4
+
+    # Commands to never suggest. Still work when typed explicitly.
+    # Example: ["/refine-ticket", "/work"]
+    blocklist: []
+
+  # --- /create-pr behavior ---
+  #
+  # Pre-creation preview of the generated PR description.
+  # false (default): skip the title/body preview + adjust loop in
+  # /create-pr; use the generated content directly. Saves agent tokens
+  # by avoiding a re-render of the full description in chat.
+  # true: show title and body in copyable code blocks and ask for
+  # adjustments before creating the PR.
+  # /create-pr:description-only always previews — that is its sole purpose.
+  create_pr:
+    preview_description: false
+
+# --- Memory ---
+#
+# Engineering memory consolidation behaviour. Memory is entirely
+# file-backed (agents/memory/). See docs/guidelines/agent-infra/memory-access.md
+# for the retrieval contract and .augment/skills/memory-consolidation/ for
+# the four-phase loop.
+memory:
+  # Cadence for the "🧠 Memory: <hits>/<asks>" visibility line emitted
+  # after a memory-consulting step (see docs/contracts/memory-visibility-v1.md).
+  #   always = (default) emit whenever at least one memory type was asked.
+  #   auto   = emit only when ≥ 3 memory types were consulted (less noise
+  #            on shallow-retrieval steps).
+  #   never  = suppress the line entirely.
+  # The legacy `memory.visibility: off` master switch still wins over this.
+  cadence: always
+
+  # Inline-review threshold for /memory load.
+  # When the unreviewed intake stream contains more than this many
+  # entries, /memory load surfaces a top-3 preview block before the
+  # full curated load. Set to 0 to disable the inline review entirely.
+  review_threshold: 10
+
+  # Patterns redacted from transcripts before mining.
+  # The TranscriptAdapter applies these as a regex blocklist on every
+  # yielded turn. Add personal identifiers, project-internal tokens,
+  # or paths outside the repo root that must not land in intake JSONL.
+  # Example: ["api[_-]?key", "/Users/[a-z]+/Library"]
+  redact_patterns: []
+
+# --- Hooks ---
+#
+# Configuration surface for the hook dispatcher (see
+# docs/contracts/hook-architecture-v1.md). Each subkey targets one
+# concern script under scripts/hooks/ or scripts/. Defaults are safe;
+# tune only when CI surfaces a real signal.
+hooks:
+  # Concern budget gate (P3.3, lint_hook_concern_budget.py). Caps how
+  # many concerns may bind to a single (platform, event) cell and
+  # restricts fail_closed=true to an explicit Tier-1 allowlist.
+  #
+  # max_per_event — placeholder until Phase 1 of
+  # road-to-proof-not-features.md captures real session evidence.
+  # Threshold rule per roadmap: max(observed-in-Phase-1) × 1.5, rounded
+  # up. 8 = current-observed-max (5) × 1.5 = 7.5 → 8.
+  #
+  # tier1_concerns — concerns allowed to block agent execution on
+  # failure (fail_closed: true in the manifest). Promotion is explicit
+  # opt-in; keep empty until Phase 1 evidence justifies an entry.
+  #
+  # hard_fail — false = warn-only (default). Flip to true after ≥10
+  # captured sessions across host agents per
+  # road-to-distribution-and-adoption.md.
+  concern_budget:
+    max_per_event: 8
+    tier1_concerns: []
+    hard_fail: false
+
+  # PostToolUse prompt-injection scanner (road-to-security-pillar.md P3.2).
+  # Default-OFF. When enabled, scans tool output (file reads, web fetches, MCP
+  # responses) for injection signatures and WARNS in context (exit 2) — never
+  # blocks. Runtime backstop on top of the always-on untrusted-input-defense
+  # rule; detection is probabilistic. Opt in per project once you trust the
+  # signal-to-noise on your tool mix.
+  injection_scan:
+    enabled: false
+
+# --- Decision engine ---
+#
+# Controllable gates layered over the observability surface. Absent
+# block = current behaviour (observe-only, no gates fire). Enforcement
+# is strictly opt-in; the engine never silently rejects work without
+# a configured gate. See docs/contracts/decision-engine-gates.md for
+# the full schema, gate-conflict matrix, and non-TTY timeout protocol.
+#
+# Gate-conflict resolution (only the first firing gate per phase
+# surfaces a reason; downstream gates are skipped):
+#   1. block_on_risk         (Phase=Implement, highest impact)
+#   2. require_memory_hits   (Phase=Refine)
+#   3. min_confidence        (Phase=Plan, lowest impact)
+#
+# Unknown keys are rejected hard by scripts/validate_decision_engine.py
+# (wired into `task ci`). Removing the entire block restores observe-only.
+decision_engine:
+  # Opt-in for DecisionTraceHook (default false). Mirrored into
+  # hooks.decision_trace.enabled by work_engine.hooks.settings.
+  surface_traces: false
+
+  # Confidence-band floor for Phase=Plan.
+  #   off    = no floor (default)
+  #   low    = refuse to advance when band is below low
+  #   medium = refuse when below medium
+  #   high   = refuse when below high
+  min_confidence: off
+
+  # Risk-class ceiling for Phase=Implement.
+  #   off    = no ceiling (default)
+  #   low    = refuse when risk_class >= low (most aggressive)
+  #   medium = refuse when risk_class >= medium
+  #   high   = refuse only when risk_class == high
+  block_on_risk: off
+
+  # Phase=Refine demands at least one memory hit when true (default false).
+  # Gated on road-to-proof-not-features.md P2 (memory-consequence trace);
+  # leaving this off avoids opaque rejections until the trace can explain
+  # which memory entry was missing.
+  require_memory_hits: false
+
+  # What happens when a gate fires.
+  #   stop = halt the engine with reason on the trace (default)
+  #   ask  = prompt the user; falls back to on_block_fallback in CI
+  #   warn = log the reason but advance
+  on_block: stop
+
+  # Non-TTY timeout (seconds) when on_block=ask runs without a TTY
+  # (CI=true env or stdin not a TTY). After the timeout, the engine
+  # applies on_block_fallback and surfaces block_reason=ask_timeout.
+  ask_timeout_seconds: 30
+
+  # Resolution after ask_timeout fires.
+  #   stop = halt the engine (default — fail-safe)
+  #   warn = log and advance
+  on_block_fallback: stop
+
+# --- Update check ---
+#
+# Daily background check against the npm registry for a newer
+# @event4u/agent-config release. When enabled the dispatcher writes a
+# two-line banner to stderr **after** the subcommand finishes; CI,
+# non-TTY stdout, and `AGENT_CONFIG_NO_UPDATE_CHECK=1` always suppress
+# it regardless of this flag. State is persisted at
+# `~/.event4u/agent-config/update-check.json` (mode 0600; legacy
+# `~/.config/agent-config/update-check.json` read as fallback) with a 24 h
+# cadence. See docs/customization.md § "Update check" for the suppression
+# matrix and the road-to-portable-runtime-and-update-check roadmap (P2).
+update_check:
+  enabled: true
+
+# ─── explain ──────────────────────────────────────────────────────────────
+# `agent-config explain last` renders the read-only execution trace for the
+# most recent /work run (state file `.work-state.json`). Trace output is
+# PII-scrubbed before emission; the command never makes network calls and
+# never writes to state. Set `enable_last: false` to suppress the subcommand
+# (the call still exits 0 with a one-line notice — used by air-gapped
+# tenants that disable diagnostics surface-wide).
+explain:
+  enable_last: true
+
+# ─── secrets ────────────────────────────────────────────────────────────────
+# Local-only secret material. This whole file is gitignored, so the key never
+# enters the tracked tree.
+#
+# link_encryption_key — symmetric key used to encrypt/decrypt stored
+# third-party package links (e.g. the source / author / pin fields in
+# agents/settings/contexts/skills-provenance.yml). Source-identifying values
+# are committed only as `ENC1:` tokens; this key is what reads them back.
+#
+# Resolution order (see src/scripts/_lib/link_crypto.py):
+#   1. this project file  → secrets.link_encryption_key
+#   2. user-global        → ~/.event4u/agent-config/agent-settings.yml
+# Decryption tries the project key first and falls back to the user-global
+# key. Keep the key in your user-global settings so encrypted provenance stays
+# recoverable across fresh clones.
+#
+# Generate one:  python3 src/scripts/_lib/link_crypto.py keygen
+# secrets:
+#   link_encryption_key: "<paste generated key here>"