@event4u/agent-config 1.13.0 → 1.14.0

package/.agent-src/skills/refine-prompt/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: "refine-prompt"
+description: "Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'."
+personas:
+  - developer
+  - senior-engineer
+  - ai-agent
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# Refine Prompt
+
+> Move a free-form prompt from "raw text" to "engine-ready" in one run.
+> Produces reconstructed acceptance criteria, explicit assumptions,
+> and a confidence band that decides whether the engine proceeds
+> silently, halts for confirmation, or refuses to plan.
+>
+> Sibling of [`refine-ticket`](../refine-ticket/SKILL.md) — same
+> reconstruction-of-intent pattern, different input shape. Tickets
+> arrive structured (id, title, AC); prompts arrive as one string.
+
+## When to use
+
+- The user invokes `/work "<prompt>"` or pastes a free-form request.
+- The dispatcher hits `input.kind="prompt"` in the `refine` step.
+- A prompt looks ambiguous, broad, or scope-undefined and the user
+  asks "ist das klar genug, um loszulegen?".
+- Before any plan/apply step on prompt-driven work — never after.
+
+## When NOT to use (near-misses)
+
+| Phrasing | Route to |
+|---|---|
+| "refine this ticket" | [`refine-ticket`](../refine-ticket/SKILL.md) |
+| "estimate this prompt" | not supported — score then estimate downstream |
+| "plan this feature" | `/feature-plan` (downstream) |
+| "is this a duplicate?" | `validate-feature-fit` (sub-skill, post-refine) |
+
+`refine-prompt` is the *first* gate on prompt-driven flow. It does not
+plan, does not implement, does not write back anywhere.
+
+## Input
+
+Exactly one path: a non-empty raw string carried in
+`state.input.data.raw` (built by [`work_engine.resolvers.prompt`](../../templates/scripts/work_engine/resolvers/prompt.py)).
+No branch detection, no URL parsing, no clipboard fallback — the
+calling command (`/work`) owns prompt capture; this skill only refines.
+
+If `raw` is missing, empty, or whitespace-only the resolver already
+raised `PromptResolverError`. The skill never receives that input.
+
+## Procedure
+
+### 1. Read and analyze the prompt
+
+Examine the raw text top to bottom *before* changing anything in
+state. Identify the *single* desired outcome in one sentence —
+verb + object + observable result. If the prompt names two
+unrelated outcomes (e.g. "fix login AND refactor the dashboard"),
+record both but flag scope-overload in step 5; the score will
+land in `medium` or `low`.
+
+This is an analysis pass, not an execution pass. The skill does
+not modify the prompt, infer code changes, or call any tool — it
+investigates the input and produces a structured envelope the
+dispatcher reads.
+
+### 2. Enumerate explicit constraints
+
+Pull every concrete signal from the prompt verbatim:
+
+- **Files / modules** named in the text (`UserController`,
+  `auth.service.ts`, `migrations/2024_…`).
+- **Behaviour anchors** — endpoints, routes, commands, fixtures.
+- **Hard rules** — "must not break X", "without changing the API",
+  "keep backwards compat".
+
+Constraints come from the prompt only. Inferred constraints belong in
+step 3 (assumptions), never here.
+
+### 3. Infer reasonable assumptions
+
+Anything the prompt implies but does not state. Examples:
+
+- "fix the login bug" → assumes the bug is in the existing `auth/`
+  module (no new auth provider).
+- "add caching" → assumes the project's primary cache driver
+  (per `.agent-settings.yml` / `config/cache.php`).
+- "speed up the export" → assumes "faster" means runtime, not memory.
+
+Each assumption is a single line, prefixed with `assumes:`. The
+medium-band halt surfaces them verbatim — no rewording, no
+explanations.
+
+### 4. Generate the AC list
+
+Three to seven bullet points. Each bullet is observable and
+testable in the project's existing test surface (Pest / Jest /
+pytest / etc.). Avoid:
+
+- "works correctly" / "is fast" / "looks better" (untestable)
+- "no regressions" (the test suite already covers that)
+- "follows best practices" (not an AC)
+
+Anchor each bullet to a constraint from step 2 or an assumption from
+step 3 — never both implicit.
+
+### 5. Score confidence
+
+Delegate to [`scripts.work_engine.scoring.confidence`](../../templates/scripts/work_engine/scoring/confidence.py):
+
+```python
+from work_engine.scoring.confidence import score
+result = score(raw=prompt_raw, ac=reconstructed_ac, assumptions=assumptions)
+# result.band ∈ {"high", "medium", "low"}
+# result.score ∈ [0.0, 1.0]
+# result.dimensions: dict[str, int]   # 0–2 per dimension
+# result.reasons: list[str]            # human-readable rationale
+```
+
+The rubric (5 dimensions × 0–2, sum / 10) and band thresholds
+(`high ≥ 0.8`, `medium 0.5–0.79`, `low < 0.5`) are owned by
+`confidence.py`. Do not re-derive them in prose.
+
+## Band-action mapping
+
+The `refine` dispatcher step in `directives/backend/refine.py` reads
+the score and returns one of three outcomes — the skill does not
+decide the action, only produces the inputs.
+
+| Band | Outcome | What the user sees |
+|---|---|---|
+| `high` | `SUCCESS` | Silent proceed; AC + assumptions land in the delivery report |
+| `medium` | `PARTIAL` | Assumptions report halt: numbered list of `assumes:` lines + AC, user confirms or edits |
+| `low` | `BLOCKED` | One clarifying question (per [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) Iron Law) |
+
+## Output format
+
+The skill emits a structured envelope; the dispatcher renders it.
+Required fields, in order:
+
+1. **Goal** — single sentence, verb + object + observable result
+2. **Acceptance criteria** — numbered list, 3–7 entries, each
+   anchored to a step-2 constraint or a step-3 assumption
+3. **Assumptions** — bullet list, each line prefixed `assumes:`
+4. **Confidence** — band + score + per-dimension breakdown from
+   `work_engine.scoring.confidence`
+
+The shape below is the rendered surface for `medium` / `low`
+halts; for `high` the same envelope lands in the delivery report
+without a halt.
+
+````markdown
+## Reconstructed prompt
+
+**Goal:** <one sentence, verb + object + observable result>
+
+**Acceptance criteria:**
+1. <bullet>
+2. <bullet>
+3. <bullet>
+
+**Assumptions:**
+- assumes: <line>
+- assumes: <line>
+
+**Confidence:** medium (0.62) — goal_clarity 2 · scope_boundary 1 · ac_evidence 2 · stack_data 1 · reversibility 0
+````
+
+For `low`, the question replaces the AC list:
+
+```
+> The prompt does not name <missing dimension>.
+>
+> 1. <option that resolves the gap>
+> 2. <alternative resolution>
+> 3. <skip / abandon>
+```
+
+## Gotchas
+
+- The model invents AC that *sound* observable but aren't anchored
+  in the prompt or a concrete file. Every AC must trace to a step-2
+  constraint or a step-3 assumption — no free-floating bullets.
+- Assumptions are not commitments. The medium-band halt is the
+  user's chance to flip them; the skill never asserts an assumption
+  as fact.
+- The scorer is heuristic, not LLM-based. Token count is not a
+  signal — a 200-word prompt can score `low` if the goal is vague,
+  and a 20-word prompt can score `high` if scope is unambiguous.
+- UI-shaped prompts ("redesign the dashboard", "make the form
+  prettier") score `low` on `stack_data` until R3 lands the UI
+  directive set; band-action is a pointer to R3, not a refusal.
+
+## Do NOT
+
+- Do NOT call this skill on `input.kind="ticket"` — that path runs
+  through [`refine-ticket`](../refine-ticket/SKILL.md).
+- Do NOT auto-confirm assumptions on the user's behalf in the
+  medium-band halt. The halt is the contract.
+- Do NOT stack multiple clarifying questions in the low-band halt.
+  Iron Law: one question per turn.
+- Do NOT mutate `state.input.data.raw`. The original prompt stays
+  verbatim for replay; reconstructed output lands in
+  `data.reconstructed_ac` and `data.assumptions`.
+- Do NOT re-derive band thresholds in prose. They live in
+  `confidence.py` and only there.
+
+## See also
+
+- [`refine-ticket`](../refine-ticket/SKILL.md) — sibling for ticket-shaped input
+- [`work_engine.resolvers.prompt`](../../templates/scripts/work_engine/resolvers/prompt.py) — envelope builder
+- [`work_engine.scoring.confidence`](../../templates/scripts/work_engine/scoring/confidence.py) — rubric + band thresholds
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one-question-per-turn Iron Law
+- [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — this skill was drafted under it
+- `agents/roadmaps/archive/road-to-prompt-driven-execution.md` — Phase 3 owns this skill (archived on completion)

package/.agent-src/skills/refine-ticket/SKILL.md

@@ -130,7 +130,7 @@ Then run the deterministic detection helper — do **not** re-derive trigger
 logic in prose:
 
 ```bash
-python3 scripts/refine_ticket_detect.py <ticket-body-file>
+./agent-config refine-ticket:detect <ticket-body-file>
 # or, inside the skill run:
 from scripts.refine_ticket_detect import detect, load_map
 decision = detect(ticket_body, load_map(), cwd=Path.cwd())
@@ -206,8 +206,7 @@ open a planning doc.
 
 ## Output template
 
-Frozen per Q25 (see
-[`road-to-ticket-refinement.md`](../../../agents/roadmaps/road-to-ticket-refinement.md)).
+Frozen per Q25.
 
 ````markdown
 ## Refined ticket
@@ -306,5 +305,4 @@ re-probe on project change.
 - [`feature-explore`](../../commands/feature-explore.md) — upstream idea capture; hints at `/refine-ticket` when input looks like a ticket
 - [`feature-plan`](../../commands/feature-plan.md) — downstream planning
 - [`adversarial-review`](../adversarial-review/SKILL.md) — same `critical-challenger` persona, different stage (post-plan)
-- [`road-to-ticket-refinement.md`](../../../agents/roadmaps/road-to-ticket-refinement.md) — governing roadmap
 - [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — this skill was drafted under it

package/.agent-src/skills/roadmap-management/SKILL.md

@@ -138,8 +138,14 @@ Every roadmap implicitly includes these gates (run after each step that changes
 1. Ask the user for goal, context-create, and phases.
 2. Use the template structure from `.augment/templates/roadmaps.md`.
 3. Review with the user iteratively until approved.
-4. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
-5. Regenerate the dashboard so the new roadmap is included.
+4. **Branch & release questions — ask at most once, only if genuinely useful.**
+   Default: stay on current branch, no version numbers in roadmap.
+   Only propose a separate branch with concrete evidence (e.g. risky
+   migration → spike branch). Never include releases, deprecation dates,
+   or git tags in roadmap text. If user declines, do **not** re-propose
+   during `roadmap-execute`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
+6. Regenerate the dashboard so the new roadmap is included.
 
 ### Executing a roadmap
 
@@ -303,4 +309,5 @@ The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate
 - Do NOT archive roadmaps with open `[ ]` items without asking the user.
 - Do NOT delete roadmaps — always move to `archive/` or `skipped/`.
 - Do NOT use `skipped/` as a dumping ground for partially-finished work — that is what `archive/` with deferred items is for.
-- Do NOT assign version numbers, git tags, or release identifiers to phases. Roadmaps plan work; releases and tags are decided by the user separately.
+- Do NOT assign version numbers, git tags, deprecation dates, or release identifiers to phases. Hard rule — see [`scope-control`](../../rules/scope-control.md#git-operations--permission-gated).
+- Do NOT propose a branch switch while executing a roadmap. Branch question is settled at creation; declined or never-asked = silent. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).

package/.agent-src/skills/rule-writing/SKILL.md

@@ -4,6 +4,8 @@ description: "Use when creating or editing a rule in .agent-src.uncompressed/rul
 source: package
 ---
 
+<!-- cloud_safe: degrade -->
+
 # rule-writing
 
 ## When to use
@@ -100,7 +102,8 @@ the PR or split by responsibility.
   → must report **0 FAIL**.
 * Run `bash scripts/compress.sh --sync` to regenerate `.agent-src/rules/{name}.md`.
 * Run `python3 scripts/compress.py --generate-tools` to project into `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`.
-* Run the full CI pipeline locally — each script directly — must exit 0 except for tolerated warnings.
+* Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
+  the script list) — must exit 0 except for tolerated warnings.
 
 ## Frontmatter shape
 
@@ -137,6 +140,25 @@ source: package           # or project for consumer-local rules
 * Do NOT skip the linter
 * Do NOT create a rule when a guideline or skill is the right shape
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's
+`scripts/skill_linter.py`, `scripts/compress.py`, and `task` runner
+are not reachable. The skill still applies — with prose-only
+validation:
+
+* Emit the full rule file as a copyable Markdown block. Do not
+  attempt to write to disk.
+* Self-check the frontmatter against the rules: `type` is `always`
+  or `auto`, `description` is trigger-shaped, `alwaysApply` matches
+  `type`.
+* Self-check the body: under the size budget (200 lines hard,
+  120 soft), trigger sentence first, no embedded procedures.
+* Tell the user to save under `.agent-src.uncompressed/rules/{name}.md`
+  and run `task sync && task lint-skills` locally before committing.
+* Do not call the linter or compressor — they only run on the
+  user's machine.
+
 ## Examples
 
 Good description (trigger-shaped, names domain + symptoms):

package/.agent-src/skills/skill-writing/SKILL.md

@@ -173,9 +173,7 @@ Present the stub as a numbered-options prompt (per `user-interaction`):
 ```
 
 Nothing is committed without the user's pick. If the user picks *skip*,
-record it in the commit message (`Eval stub: deferred`). See
-[`road-to-trigger-evals.md`](../../../agents/roadmaps/archive/road-to-trigger-evals.md)
-Phase 1 for the runner and expected format; peer examples:
+record it in the commit message (`Eval stub: deferred`). Peer examples:
 `php-coder/evals/triggers.json`, `eloquent/evals/triggers.json`,
 `skill-writing/evals/triggers.json`.
 

package/.agent-src/skills/upstream-contribute/SKILL.md

@@ -182,7 +182,7 @@ If the contribution originates from a proposal under `agents/proposals/`
 run the Stage-4 gate before opening the PR:
 
 ```bash
-python3 scripts/check_proposal.py agents/proposals/{slug}.md
+./agent-config proposal:check agents/proposals/{slug}.md
 ```
 
 **Hard refusal rule:** if `check_proposal.py` exits non-zero, STOP —

package/.agent-src/skills/using-git-worktrees/SKILL.md

@@ -68,10 +68,12 @@ Stop at the first match — do not ask if discovered:
 
 Ask format:
 
-> 1. `.worktrees/` — project-local, hidden (recommended)
+> 1. `.worktrees/` — project-local, hidden
 > 2. `worktrees/` — project-local, visible
 > 3. `~/.config/agent-config/worktrees/<project>/` — global
 
+**Recommendation: 1 — `.worktrees/`** — project-local keeps the worktree next to the repo (easy cleanup), and the leading dot keeps it out of `ls`. Caveat: pick 3 if multiple repos must share a single worktree root.
+
 ### 3. Verify ignore-safety (project-local only)
 
 ```bash

package/.agent-src/templates/AGENTS.md

@@ -34,12 +34,30 @@
 
 ### Recommended entry flow
 
-For most tickets — feature, bug fix, or refactor — start with
-[`/implement-ticket`](.augment/commands/implement-ticket.md). It drives the
-linear flow `refine → memory → analyze → plan → implement → test → verify →
-report` with block-on-ambiguity semantics and no auto-git. Persona comes from
-`.agent-settings.yml` (`roles.active_role`). Use `/commit` and `/create-pr`
-explicitly after the delivery report.
+Two entrypoints share the same engine and Option-A loop; pick by input shape:
+
+| You have | Command | Envelope |
+|---|---|---|
+| Ticket id, URL, or pasted ticket payload | [`/implement-ticket`](.augment/commands/implement-ticket.md) | `input.kind="ticket"` |
+| Free-form goal, no ticket | [`/work`](.augment/commands/work.md) | `input.kind="prompt"` |
+
+Both drive the linear flow `refine → memory → analyze → plan → implement →
+test → verify → report` with block-on-ambiguity semantics and no auto-git.
+
+`/work` adds a confidence-band gate at `refine`: the
+[`refine-prompt`](.augment/skills/refine-prompt/SKILL.md) skill scores the
+prompt on five dimensions and the engine proceeds **silently** on `high`,
+halts with an **assumptions report** on `medium`, or halts with **one
+clarifying question** on `low` (per the `ask-when-uncertain` Iron Law).
+UI-shaped prompts route through the product UI track (`directive_set`
+`ui` / `ui-trivial` / `mixed`) — `audit → design → apply → review →
+polish` with a hard audit gate before any `apply`.
+
+Persona comes from `.agent-settings.yml` (`roles.active_role`). Use
+`/commit` and `/create-pr` explicitly after the delivery report. The two
+flows are mutually exclusive at the state-file level: one
+`.work-state.json` carries one envelope at a time; the engine refuses to
+switch mid-flight.
 
 ### Multi-Agent Support
 

package/.agent-src/templates/agent-settings.md

@@ -84,6 +84,15 @@ personal:
   # Personal preference — each developer decides for themselves.
   pr_comment_bot_icon: 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
+
 # --- Project / team preferences ---
 project:
   # Path to the PR template file (relative to project root)
@@ -132,6 +141,74 @@ chat_history:
   # Overflow behavior: rotate (drop oldest) | compress (summarize)
   on_overflow: rotate
 
+  # Heartbeat marker visibility: on | off | hybrid
+  #   on     — print marker every reply (~20 tokens/reply, legacy)
+  #   off    — never print (zero tokens, no drift signal)
+  #   hybrid — print only on drift (missing/foreign/returning); silent otherwise
+  # YAML 1.1 booleanizes bare on/off — both are accepted, no quoting needed.
+  heartbeat: hybrid
+
+  # Population path: hook | checkpoint | manual
+  #   hook       — platform fires lifecycle hooks; agent observes only
+  #                (Claude Code, Augment CLI, Cursor 1.7+, Cline non-Windows,
+  #                 Windsurf, Gemini CLI). scripts/install.py wires hooks.
+  #   checkpoint — agent invokes /chat-history-checkpoint at phase boundaries
+  #                (Augment IDE plugin, Cursor < 1.7, Cline on Windows).
+  #                Cooperative three-gate Iron Law applies.
+  #   manual     — rule is inert (cloud surfaces). Persistence is local-only.
+  # Default `checkpoint` is the safest cooperative fallback. HOOK platforms
+  # set this to `hook` automatically when scripts/install.py merges the
+  # platform's settings file.
+  path: checkpoint
+
+# --- Work-engine hooks ---
+#
+# Lifecycle hook surface of the `work_engine` Python engine
+# (scripts/work_engine/). Hooks observe, validate, or persist around the
+# six CLI events (before_load, after_load, before_dispatch,
+# after_dispatch, before_save, after_save) and the dispatcher events
+# (before_step, after_step, on_halt). See agents/contexts/
+# work-engine-hooks.md for the full lifecycle and registration contract.
+#
+# Default-off by construction: when the `hooks:` block is absent the
+# registry stays empty and golden-replay flows are byte-stable. Enable
+# the master switch to opt in; per-hook flags then control individual
+# registration.
+hooks:
+  # Master switch — when false (default) the registry stays empty
+  # regardless of the per-hook fields below.
+  enabled: false
+
+  # TraceHook — emits per-event trace lines on stderr. Useful for
+  # debugging engine flow; off by default because it is noisy.
+  trace: false
+
+  # HaltSurfaceAuditHook — defense-in-depth check that every halt
+  # surfaced by the dispatcher carries the expected shape. Cheap.
+  halt_surface_audit: true
+
+  # StateShapeValidationHook — re-runs the state schema validator on
+  # AFTER_LOAD and BEFORE_SAVE. Cheap, catches drift between the
+  # in-memory state and the persisted JSON.
+  state_shape_validation: true
+
+  # DirectiveSetGuardHook — verifies the directive-set resolved by the
+  # dispatcher matches the input envelope's intent. Cheap, catches
+  # routing drift.
+  directive_set_guard: true
+
+  # Chat-history hooks — populate .agent-chat-history structurally from
+  # the engine. Gated by BOTH this block AND the global
+  # chat_history.enabled above; either off → no chat-history hook
+  # registers. Keep both on for the HOOK path; flip either off to fall
+  # back to the cooperative CHECKPOINT path.
+  chat_history:
+    enabled: true
+    # Override path to the chat-history CLI (defaults to
+    # scripts/chat_history.py). Only set this when the script lives
+    # outside the standard location.
+    # script: scripts/chat_history.py
+
 # --- Optional pipelines ---
 pipelines:
   # Skill improvement pipeline (true, false)
@@ -193,6 +270,58 @@ onboarding:
   # 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.md`.
+commands:
+  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.
+    confidence_floor: 0.6
+    # Cooldown in seconds between re-suggestions of the same
+    # (command, evidence) pair. Default 600 = 10m.
+    cooldown_seconds: 600
+    # Max number of command suggestions before the as-is option.
+    # The as-is option is always extra (total rendered = max_options + 1).
+    max_options: 4
+    # Commands to never suggest. Still work when typed explicitly.
+    blocklist: []
+
+# --- Telemetry (artefact engagement, default-off) ---
+#
+# Records — at task / phase-step boundaries — which artefacts (skills,
+# rules, commands, guidelines, personas) the agent consulted and
+# applied. Local only, append-only JSONL, never reaches a consumer
+# repo (gitignored). Maintainer-targeted feature; consumers leave it
+# off. See `agents/contexts/artifact-engagement-flow.md` (once Phase 3
+# of road-to-artifact-engagement-telemetry lands).
+telemetry:
+  artifact_engagement:
+    # Master switch. `false` (default) produces zero file IO and zero
+    # token cost. Flip to `true` only as a maintainer; the very first
+    # `record` call prints a one-line stderr warning to make accidental
+    # enables visible.
+    enabled: false
+    # `task` = one event per /implement-ticket or /work run.
+    # `phase-step` = one event per refine|memory|analyze|plan|implement|test|verify|report step.
+    # `tool-call` = one event per tool invocation; expensive, opt-in only.
+    granularity: task
+    # Which categories the agent records. Both default to `true`;
+    # flip individually if a maintainer wants applied-only or
+    # consulted-only data.
+    record:
+      consulted: true
+      applied: true
+    output:
+      # Append-only JSONL log. Path is relative to the project root.
+      # Always gitignored (see config/gitignore-block.txt).
+      path: .agent-engagement.jsonl
 ```
 
 ## Settings Reference
@@ -213,6 +342,7 @@ lives under `personal:` in YAML.
 | `personal.minimal_output` | `true`, `false` | `true` | When `true`: short bullet points during work, concise summary at end. When `false`: verbose explanations. |
 | `personal.play_by_play` | `true`, `false` | `false` | When `true`: share intermediate findings during investigation. When `false`: work silently, report only the conclusion. |
 | `personal.pr_comment_bot_icon` | `true`, `false` | `false` | Prefix PR comment replies with 🤖 to indicate bot-authored replies. Personal preference — each developer decides. |
+| `personal.autonomy` | `on`, `off`, `auto` | `auto` | Suppress trivial workflow questions and act on the obvious next step. `auto` defaults to `off` but flips to `on` after a prose opt-in like "arbeite selbstständig". `on` suppresses trivial questions unconditionally. Blocking decisions (security, scope expansion, push/merge/branch/PR/tag) are never suppressed. See `rules/autonomous-execution.md`. |
 | `project.pr_template` | file path | `.github/pull_request_template.md` | Path to PR template file. Read this instead of searching for it. |
 | `project.upstream_repo` | `org/repo` | _(empty)_ | Target repository for universal improvement PRs (e.g., `org/agent-config`). |
 | `project.improvement_pr_branch_prefix` | string | `improve/agent-` | Branch prefix for agent improvement PRs. |
@@ -222,6 +352,15 @@ lives under `personal:` in YAML.
 | `chat_history.frequency` | `per_turn`, `per_phase`, `per_tool` | per profile | Logging granularity. Defaults: `minimal`→`per_turn`, `balanced`→`per_phase`, `full`→`per_tool`. |
 | `chat_history.max_size_kb` | integer | per profile | Max file size before overflow handling. Defaults: `minimal`→`128`, `balanced`→`256`, `full`→`512`. |
 | `chat_history.on_overflow` | `rotate`, `compress` | per profile | On overflow: `rotate` drops oldest entries; `compress` marks the file for summarization on the next turn. Defaults: `minimal`/`balanced`→`rotate`, `full`→`compress`. |
+| `chat_history.heartbeat` | `on`, `off`, `hybrid` | `hybrid` | Visibility of the `📒 chat-history:` marker. `on` = every reply (~20 tokens), `off` = silent, `hybrid` = print only on drift states (`missing`/`foreign`/`returning`). YAML `on`/`off` accepted bare. |
+| `chat_history.path` | `hook`, `checkpoint`, `manual` | `checkpoint` | Population path. `hook` = platform fires lifecycle hooks; `checkpoint` = agent invokes `/chat-history-checkpoint` at phase boundaries; `manual` = rule inert (cloud). `scripts/install.py` flips this to `hook` when the platform's hook config is deployed. See [`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md). |
+| `hooks.enabled` | `true`, `false` | `false` | Master switch for the work-engine hook layer. When `false` (default) the registry stays empty and golden replay is byte-stable. See [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md). |
+| `hooks.trace` | `true`, `false` | `false` | Emit per-event trace lines on stderr. Useful for debugging; off by default because it is noisy. |
+| `hooks.halt_surface_audit` | `true`, `false` | `true` | Defense-in-depth check that every halt surfaced by the dispatcher carries the expected shape. Cheap. |
+| `hooks.state_shape_validation` | `true`, `false` | `true` | Re-run the state schema validator on `AFTER_LOAD` and `BEFORE_SAVE`. Cheap, catches drift. |
+| `hooks.directive_set_guard` | `true`, `false` | `true` | Verify the dispatcher-resolved directive set matches the input envelope intent. Cheap, catches routing drift. |
+| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the four chat-history hooks (turn-check, append, halt-append, heartbeat). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. |
+| `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
@@ -231,6 +370,16 @@ lives under `personal:` in YAML.
 | `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../guidelines/agent-infra/layered-settings.md). |
 | `personas.ignore` | list of persona ids | `[]` | Persona ids dropped from the default cast locally. Ignored personas stay invokable via `--personas=<id>`. |
 | `onboarding.onboarded` | `true`, `false` | `false` | Whether `/onboard` has run on this project. The `onboarding-gate` rule prompts for `/onboard` when this is `false`. Missing entirely = legacy project, treated as onboarded. |
+| `commands.suggestion.enabled` | `true`, `false` | `true` | Master switch for the command-suggestion layer. `false` = the layer is silent; explicit `/commands` still work. See `rules/command-suggestion.md`. |
+| `commands.suggestion.confidence_floor` | `0.0`–`1.0` | `0.6` | Minimum match score before a suggestion surfaces. Per-command frontmatter (`suggestion.confidence_floor`) overrides this global floor. |
+| `commands.suggestion.cooldown_seconds` | integer | `600` | Cooldown between re-suggestions of the same `(command, evidence)` pair. `600` = 10m. |
+| `commands.suggestion.max_options` | integer | `4` | Max number of command suggestions before the always-present "run as-is" option (total rendered = `max_options + 1`). |
+| `commands.suggestion.blocklist` | list of command names | `[]` | Commands that never appear as a suggestion. They still work when typed explicitly. |
+| `telemetry.artifact_engagement.enabled` | `true`, `false` | `false` | Master switch for the artefact engagement log. Default-off; zero file IO and zero token cost when `false`. Maintainer-targeted; consumers leave it off. |
+| `telemetry.artifact_engagement.granularity` | `task`, `phase-step`, `tool-call` | `task` | Boundary at which events are recorded. `tool-call` is expensive — opt-in only. |
+| `telemetry.artifact_engagement.record.consulted` | `true`, `false` | `true` | When `true`: record artefacts loaded into context. |
+| `telemetry.artifact_engagement.record.applied` | `true`, `false` | `true` | When `true`: record artefacts cited or driving a decision. |
+| `telemetry.artifact_engagement.output.path` | path | `.agent-engagement.jsonl` | Append-only JSONL log path, relative to the project root. Always gitignored. |
 
 ### Rename-Map (migration)
 

package/.agent-src/templates/roadmaps.md

@@ -27,8 +27,14 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
 
 13. **No tags, releases, or version numbers.** Roadmaps describe work, not shipping.
     Never assign version suffixes to phases (`Phase 1 — v1.8.0`), never write
-    "Target release: X.Y.Z", never plan git tags. Release and tag decisions
-    belong to the user and are taken outside the roadmap.
+    "Target release: X.Y.Z", never plan git tags or deprecation dates. Release
+    and tag decisions belong to the user, taken outside the roadmap. Enforced by
+    [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
+14. **No automatic branch switches mid-roadmap.** Roadmap work runs on the
+    current branch. If a separate branch (spike, hotfix, experiment) would
+    be useful, agent may propose it **once** during creation — not during
+    execution. Default: stay on current branch. If user declines, topic is
+    closed for this roadmap. See [`scope-control`](../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
 
 ---