@event4u/agent-config 1.13.0 → 1.15.0

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

@@ -30,12 +30,13 @@ the dashboard **in the same response**.
 `count_open == 0` (pure `[x]`, or `[x]` + `[~]`/`[-]`), `git mv`
 it into `agents/roadmaps/archive/` **before** regenerating — see
 the auto-archive decision table under "Check completion status"
-below. A 100%-complete roadmap left in `agents/roadmaps/` makes
-the next reader think work is still open.
+below. A 100%-complete roadmap left in `agents/roadmaps/` makes the
+next reader think work is still open.
 
-Enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md).
-Batching edits in one response is fine — one final regeneration before
-replying is enough. But the response must not end without it.
+This is enforced by the [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+rule. Batching multiple edits in one response is fine — one final
+regeneration before replying is enough. But the response must not end
+without it.
 
 ## Procedure: Manage a roadmap
 
@@ -100,11 +101,13 @@ Every roadmap follows this structure:
 
 ## Key rules for roadmaps
 
-### Checkboxes
+### Checkboxes — mandatory, not decorative
 
+- **Every active roadmap MUST contain at least one `- [ ]` per non-intro phase.** Decision tables, ICE matrices, and block-sequencing tables are valid rationale, but they do not satisfy this rule on their own — pair them with a `## Phase N` or `## Implementation Checklist` section whose checkboxes execute the decision. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` and violates [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) Iron Law #2.
 - Every actionable step uses `- [ ]` (unchecked) or `- [x]` (completed).
 - Mark steps as `[x]` immediately after completing them.
 - Never remove completed steps — they serve as history.
+- **Status is binary: `ready` (default, implicit) or `draft`.** New roadmaps are created **ready** unless the user explicitly says otherwise — `ready` is implicit and need not be written. A roadmap that is still being authored, awaiting upstream decisions, or capturing options without a worked plan declares `status: draft` in YAML frontmatter at the top of the file. Drafts are hidden from `agents/roadmaps-progress.md` until the flag is removed or flipped to `ready`. There are no other status values; legacy banners (`**Status: directional**`, `Status: capture-only`, `mode: feedback`) are removed.
 
 ### Phases
 
@@ -138,8 +141,15 @@ 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 — at most once, only if genuinely useful.**
+   Default: stay on the current branch, no version numbers in the
+   roadmap. Only propose a separate branch when there is concrete,
+   evidence-based reason (e.g. risky migration benefits from a spike).
+   Never include release versions, deprecation dates, or git tags in
+   the roadmap text. If the 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
 
@@ -266,8 +276,10 @@ Command:
 ./agent-config roadmap:progress-check     # CI: fail if stale
 ```
 
-The `./agent-config` wrapper is written into the project root by the
-installer and always works — no global tooling or task runner required.
+The `./agent-config` wrapper lives in the project root (written by the
+package installer, gitignored) and delegates to the master CLI inside
+`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
+No global tooling required.
 
 The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate it.
 
@@ -303,4 +315,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. Roadmaps plan work; releases and tags are decided by the user separately. Hard rule — see [`scope-control`](../../rules/scope-control.md#git-operations--permission-gated).
+- Do NOT propose a branch switch while executing a roadmap. The branch question is settled at creation time; if the user already declined (or you never asked because it wasn't sensible), stay 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,11 +173,9 @@ 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:
-`php-coder/evals/triggers.json`, `eloquent/evals/triggers.json`,
-`skill-writing/evals/triggers.json`.
+record it in the commit message (`Eval stub: deferred`). Peer examples
+for the expected format: `php-coder/evals/triggers.json`,
+`eloquent/evals/triggers.json`, `skill-writing/evals/triggers.json`.
 
 Rules / commands / guidelines do **not** get eval stubs — only skills
 route through the top-level catalogue.

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

@@ -182,10 +182,10 @@ 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 —
+**Hard refusal rule:** if `./agent-config proposal:check` exits non-zero, STOP —
 do not create the branch, do not push, do not open the PR. Surface the
 findings to the user, ask them to fix the proposal (add evidence,
 remove TODO markers, complete required sections), then rerun.
@@ -247,7 +247,7 @@ The shared version now replaces the local override.
 ## Do NOT
 
 - **Do NOT create any upstream artifact without explicit user consent** — this is the #1 rule
-- **Do NOT open a PR if `check_proposal.py` blocks** — fix the proposal first (step 6b)
+- **Do NOT open a PR if `./agent-config proposal:check` blocks** — fix the proposal first (step 6b)
 - Do NOT edit `.augment/` in the consumer project — it's managed by the package
 - Do NOT submit project-specific content without generalizing it first
 - Do NOT skip the compressed version — both files are mandatory

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 `docs/contracts/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

@@ -7,7 +7,8 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
 ## Rules for Roadmaps
 
 1. **Be precise and concise.** Aim for 500–1000 lines max. If larger, split into multiple files.
-2. **Use checkboxes** (`- [ ]`) for every actionable step. Mark `[x]` when completed.
+2. **Checkboxes are mandatory, not decorative.** Every active roadmap MUST contain at least one `- [ ]` per non-intro phase. Decision tables, ICE matrices, and block-sequencing tables capture the *why*; checkboxes capture the *what to do next*. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` — the dashboard cannot count it, the next reader thinks no work is planned. Enforced by [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md) Iron Law #2.
+   - **Status is binary: `ready` (default) or `draft`.** New roadmaps are created **ready** unless the user explicitly says draft — `ready` is implicit and need not be written. Drafts declare it via frontmatter at the top of the file (`---\nstatus: draft\n---`) and are hidden from the dashboard until the flag is removed or flipped to `ready`. Use `draft` while the roadmap is still being authored, while waiting for upstream decisions, or as a capture-only synthesis that has not been promoted to executable phases. There are no other status values; legacy banners like `**Status: directional**` are removed.
 3. **State the goal first.** One sentence at the top — what is the outcome?
 4. **List prerequisites** — what must exist or be running before starting.
 5. **Reference existing code** — point to files, classes, or modules.
@@ -24,11 +25,17 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
     - `agents/roadmaps/skipped/` — decision against pursuit; typically 0 items `[x]` (superseded, scope rejected)
 
     See the `roadmap-management` skill for the exact trigger matrix and user-confirmation flow.
-
 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 and are taken outside the roadmap.
+    This is enforced by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
+14. **No automatic branch switches mid-roadmap.** Roadmap work runs on the
+    branch the user is on. If a separate branch (spike, hotfix, experiment)
+    would be genuinely useful, the agent may propose it **once** while
+    creating the roadmap — not during execution. Default: stay on the
+    current branch. If the user declines, the topic is closed for this
+    roadmap. See [`scope-control`](../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
 
 ---
 

package/.agent-src/templates/scripts/implement_ticket/__init__.py

@@ -1,40 +1,77 @@
-"""/implement-ticket orchestrator — linear step dispatcher.
-
-Shipped to consumer projects via the installer. Consumer code imports
-``DeliveryState``, ``dispatch``, and the ``Outcome`` enum from this
-package; step implementations land in Phase 2 under
-``.agent-src.uncompressed/skills/implement-ticket/`` and plug into the
-``Step`` protocol exposed here.
-
-Architectural constraints (from
-``agents/contexts/adr-implement-ticket-runtime.md`` and
-``agents/contexts/implement-ticket-flow.md``):
-
-- Runtime is Python 3.10+.
-- The dispatcher is linear, not a DAG. Eight fixed steps, fixed order.
-- ``DeliveryState`` is the only object shared between steps — no
-  hidden state, no side channels.
-- Every step terminates in ``success | blocked | partial``. ``blocked``
-  and ``partial`` halt the flow and surface numbered questions.
-- The dispatcher never calls git, writes commits, or opens PRs.
+"""``implement_ticket`` — deprecated shim, retained for one release.
+
+The engine moved to :mod:`work_engine` in R1 Phase 3. This module
+re-exports the public surface so existing imports keep working, but
+emits :class:`DeprecationWarning` on import. The Golden-Transcript
+freeze-guard pins ``./agent-config implement-ticket`` against the
+locked baseline; the shim keeps that path byte-stable while internal
+callers migrate to ``work_engine``.
+
+Remove after the next public release of this package.
 """
 from __future__ import annotations
 
-from .delivery_state import (
+import sys as _sys
+import warnings as _warnings
+
+_warnings.warn(
+    "implement_ticket has moved to work_engine; importing implement_ticket "
+    "is deprecated and will be removed in a future release. Update imports "
+    "to `from work_engine import …`.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Register submodule aliases so `from implement_ticket.steps.plan import …`
+# and friends keep resolving to the work_engine implementation. The legacy
+# package no longer ships these submodules on disk; sys.modules entries
+# keep dotted-path imports working until the shim is removed.
+import work_engine as _we_pkg  # noqa: E402
+import work_engine.cli as _we_cli  # noqa: E402
+import work_engine.delivery_state as _we_delivery_state  # noqa: E402
+import work_engine.dispatcher as _we_dispatcher  # noqa: E402
+import work_engine.persona_policy as _we_persona_policy  # noqa: E402
+import work_engine.directives.backend as _we_steps  # noqa: E402
+from work_engine.directives.backend import (  # noqa: E402
+    analyze as _we_step_analyze,
+    implement as _we_step_implement,
+    memory as _we_step_memory,
+    plan as _we_step_plan,
+    refine as _we_step_refine,
+    report as _we_step_report,
+    test as _we_step_test,
+    verify as _we_step_verify,
+)
+
+_sys.modules.setdefault("implement_ticket.cli", _we_cli)
+_sys.modules.setdefault("implement_ticket.delivery_state", _we_delivery_state)
+_sys.modules.setdefault("implement_ticket.dispatcher", _we_dispatcher)
+_sys.modules.setdefault("implement_ticket.persona_policy", _we_persona_policy)
+_sys.modules.setdefault("implement_ticket.steps", _we_steps)
+_sys.modules.setdefault("implement_ticket.steps.analyze", _we_step_analyze)
+_sys.modules.setdefault("implement_ticket.steps.implement", _we_step_implement)
+_sys.modules.setdefault("implement_ticket.steps.memory", _we_step_memory)
+_sys.modules.setdefault("implement_ticket.steps.plan", _we_step_plan)
+_sys.modules.setdefault("implement_ticket.steps.refine", _we_step_refine)
+_sys.modules.setdefault("implement_ticket.steps.report", _we_step_report)
+_sys.modules.setdefault("implement_ticket.steps.test", _we_step_test)
+_sys.modules.setdefault("implement_ticket.steps.verify", _we_step_verify)
+
+from work_engine import (  # noqa: E402,F401  — re-export for backwards compat
     AGENT_DIRECTIVE_PREFIX,
+    DEFAULT_PERSONA,
+    DEFAULT_STATE_FILE,
     DeliveryState,
     Outcome,
+    PersonaPolicy,
+    STEP_ORDER,
     Step,
     StepResult,
     agent_directive,
+    dispatch,
     is_agent_directive,
-)
-from .cli import DEFAULT_STATE_FILE, main
-from .dispatcher import STEP_ORDER, dispatch
-from .persona_policy import (
-    DEFAULT_PERSONA,
-    PersonaPolicy,
     known_personas,
+    main,
     resolve_policy,
 )
 

package/.agent-src/templates/scripts/implement_ticket/__main__.py

@@ -1,9 +1,15 @@
-"""Module entry point — lets ``python3 -m implement_ticket`` run the CLI."""
+"""Deprecated CLI entry point — delegates to :mod:`work_engine`.
+
+``python3 -m implement_ticket`` still works because the Golden-Transcript
+freeze-guard pins that invocation. Internally it forwards to
+``work_engine.cli.main`` after emitting a ``DeprecationWarning`` from
+the package ``__init__``.
+"""
 from __future__ import annotations
 
 import sys
 
-from .cli import main
+from work_engine.cli import main
 
 if __name__ == "__main__":
     sys.exit(main())

package/.agent-src/templates/scripts/memory_lookup.py

@@ -246,7 +246,7 @@ def _apply_conflict_rule(
 # says retrieval should route through `@event4u/agent-memory`. The package
 # CLI is purely **semantic** (`memory retrieve <query> --type T …`); the
 # shared `retrieve(types, keys, …)` API is **key-based**. The hybrid
-# resolution agreed in `agents/contexts/agent-memory-contract.md` synthesises
+# resolution agreed in `docs/contracts/agent-memory-contract.md` synthesises
 # `keys` into a single natural-language query for the package call, while
 # the file fallback continues to do glob/substring matching on the same
 # keys. Both legs land in the same `Hit` shape so the conflict rule can

package/.agent-src/templates/scripts/telemetry/__init__.py

@@ -0,0 +1,42 @@
+"""``telemetry`` — artefact engagement recording (default-off).
+
+The package owns the local-only engagement log
+(``.agent-engagement.jsonl``) that records, at task boundaries, which
+artefacts (skills, rules, commands, guidelines, personas) the agent
+``consulted`` (loaded into context) and ``applied`` (cited or directly
+drove a decision).
+
+Architectural constraints (from
+``agents/roadmaps/road-to-artifact-engagement-telemetry.md`` Phase 1):
+
+- Default-off. ``telemetry.artifact_engagement.enabled: false`` in
+  ``.agent-settings.yml`` produces zero file IO and zero token cost.
+- Local only. No server-side aggregation, no cross-repo sync.
+- ID-only payloads. No paths, no file contents, no prompts, no
+  secrets ever reach the log.
+- Append-only JSONL. One event per task / phase-step boundary.
+- Strict schema. Unknown artefact kinds are rejected.
+"""
+from __future__ import annotations
+
+from .engagement import (
+    ALLOWED_BOUNDARY_KINDS,
+    ALLOWED_KINDS,
+    SCHEMA_VERSION,
+    EngagementEvent,
+    EngagementSchemaError,
+    append_event,
+    now_utc_iso,
+    parse_event,
+)
+
+__all__ = [
+    "ALLOWED_BOUNDARY_KINDS",
+    "ALLOWED_KINDS",
+    "SCHEMA_VERSION",
+    "EngagementEvent",
+    "EngagementSchemaError",
+    "append_event",
+    "now_utc_iso",
+    "parse_event",
+]