@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/commands/work.md

@@ -0,0 +1,161 @@
+---
+name: work
+skills: [refine-prompt, command-routing]
+description: Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "build this, implement this, drive this end-to-end"
+  trigger_context: "free-form prompt without a ticket key"
+---
+
+# work
+
+## Instructions
+
+### 1. Resolve the prompt
+
+`/work` accepts the user's request as a free-form prompt. Resolve the
+input in this order:
+
+1. **Inline argument** — `/work <prompt>` (everything after the verb is
+   the prompt; quoting is not required).
+2. **Pasted block** — markdown block under the command in the same turn.
+3. **No input** — ask once, with numbered options:
+
+   ```
+   > 1. I'll type the prompt now — paste it on the next line
+   > 2. Load from a file — give me a path
+   > 3. Abort — never mind
+   ```
+
+   On `1`, wait for the user. On `2`, ask for the path and read it. On
+   `3`, stop.
+
+Strip leading/trailing whitespace at the boundary, but preserve casing
+and internal spacing — the scorer reads the original text when grading
+goal clarity.
+
+### 2. Prepare the state file
+
+The engine persists everything in `.work-state.json` (same envelope as
+`/implement-ticket`, different `input.kind`). Two cases, in this order:
+
+- **Resume** — `.work-state.json` exists with `input.kind="prompt"`. Do
+  not pass `--prompt-file` or `--persona`; mid-flight switches are
+  refused by the engine.
+- **Fresh run** — no state file. Write the resolved prompt to
+  `prompt.txt` (raw text, single file, UTF-8) and pass it via
+  `--prompt-file prompt.txt`. Honour `roles.active_role` from
+  `.agent-settings.yml` via `--persona`.
+
+If a `.work-state.json` exists but carries a ticket envelope
+(`input.kind="ticket"`), that's an `/implement-ticket` flow in
+progress. Stop and ask:
+
+```
+> A ticket-flow state file is already in `.work-state.json`. Pick one:
+> 1. Resume the ticket flow — re-run /implement-ticket
+> 2. Discard it — delete the state file and start /work fresh
+> 3. Abort
+```
+
+### 3. Drive the Option-A dispatch loop
+
+Run the engine with the state file on every iteration:
+
+```bash
+./agent-config work \
+    --state-file .work-state.json \
+    [--prompt-file prompt.txt --persona <name>]   # first call only
+```
+
+The dispatcher wires `PYTHONPATH` and routes to the engine module
+internally. `./agent-config` is the only supported entry point in
+consumer repos — do not call the engine module directly.
+
+Branch on the exit code:
+
+| Exit | Meaning | Action |
+|---|---|---|
+| `0` | SUCCESS — final report on stdout | Go to step 5 |
+| `1` | BLOCKED — halt surface on stdout, state persisted | Inspect `questions[0]` |
+| `2` | Config/IO error | Surface the stderr message to the user, stop |
+
+On exit `1`, look at the first line after `[halt] outcome=… step=…`:
+
+- **Starts with `@agent-directive: refine-prompt`** — invoke the
+  [`refine-prompt`](../skills/refine-prompt/SKILL.md) skill against
+  `state.input.data.raw`, write the resulting `reconstructed_ac` and
+  `assumptions` arrays back onto `state.input.data`, then re-run.
+- **Starts with `@agent-directive:` (other verbs)** — see §4.
+- **Starts with `>`** — user question per
+  [`user-interaction`](../rules/user-interaction.md). Emit verbatim,
+  wait for the user, write their answer back onto `state.input.data`
+  (or the matching slice), then re-run. Never guess.
+
+### 4. Confidence-band semantics
+
+The engine's `refine` step scores the reconstructed envelope and routes
+on the resulting band. Never attempt to flip the band yourself — the
+engine owns the verdict.
+
+| Band | Outcome | What the agent does |
+|---|---|---|
+| `high` | SUCCESS | Engine proceeds silently; the breakdown lands on `state.input.data.confidence` and is included in the delivery report |
+| `medium` | PARTIAL halt | Engine emits the assumptions report; surface verbatim, wait for the user. On confirm, write `state.input.data.confidence_confirmed=true` and re-run. On refine, replace `state.input.data.raw` with the new prompt, clear `reconstructed_ac` + `assumptions`, and re-run |
+| `low` | BLOCKED halt | Engine emits exactly one clarifying question on the weakest dimension (per [`ask-when-uncertain`](../rules/ask-when-uncertain.md) Iron Law). Surface verbatim, wait for the user, append their answer to `state.input.data.raw`, clear `reconstructed_ac` + `assumptions`, and re-run |
+
+Once the gate releases, the rest of the loop is identical to
+`/implement-ticket`: `create-plan`, `apply-plan`, `run-tests`,
+`review-changes` directives flow through the same dispatch table.
+
+### 5. Final report + close-prompt
+
+On exit `0`, the engine prints the delivery report. Surface it
+unchanged, then append:
+
+```
+> 1. /commit — stage + commit per the delivery report
+> 2. /create-pr — open a pull request from this branch
+> 3. Keep working — I'll hold the state file for the next /work
+> 4. Discard — delete .work-state.json
+```
+
+Per [`scope-control`](../rules/scope-control.md), git operations are
+permission-gated. Never run `/commit` or `/create-pr` without the user
+choosing them.
+
+### Rules
+
+- Honour [`scope-control`](../rules/scope-control.md),
+  [`minimal-safe-diff`](../rules/minimal-safe-diff.md), and
+  [`verify-before-complete`](../rules/verify-before-complete.md) inside
+  every directive.
+- Never bypass the engine. Don't skip steps, don't rewrite outcomes,
+  don't flip `confidence_confirmed` without the user's explicit OK.
+- The low-band halt emits **one** question. If you find yourself
+  surfacing two, you reformatted the engine output — stop and surface
+  it verbatim.
+- Persona is session-global. Read it from `.agent-settings.yml` on the
+  fresh run; never accept a `--persona` flag from the user mid-flight.
+- When `telemetry.artifact_engagement.enabled: true` in
+  `.agent-settings.yml`, emit one `./agent-config telemetry:record` per
+  boundary (per phase-step or per task — see `granularity`) with the
+  consulted+applied artefact ids. Full contract in
+  [`artifact-engagement-recording`](../rules/artifact-engagement-recording.md).
+  Default-off; absent setting is a silent no-op.
+
+## Examples
+
+```
+/work fix the failing login test under tests/feature/auth
+/work                                # asks for the prompt
+/work add a CSV export endpoint to the audit-log controller
+```
+
+## See also
+
+- [`refine-prompt`](../skills/refine-prompt/SKILL.md) — fills `reconstructed_ac` + `assumptions` on the rebound from the first-pass halt
+- [`implement-ticket`](implement-ticket.md) — sibling command for ticket-shaped input; same engine, different envelope
+- [`commit`](commit.md), [`create-pr`](create-pr.md) — post-delivery commands the user runs explicitly

package/.agent-src/guidelines/agent-infra/engineering-memory-data-format.md

@@ -16,9 +16,8 @@ matching the existing pattern established by `review-routing-data-format`.
 ## File locations
 
 Each schema lives under `agents/memory/<type>/<hash>.yml` (content-addressed,
-merge-safe — see [`road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md))
-**or** in a single `agents/memory/<type>.yml` file for projects that prefer
-one file per type.
+merge-safe) **or** in a single `agents/memory/<type>.yml` file for projects
+that prefer one file per type.
 
 | Type | Single-file path | Sharded path |
 |---|---|---|
@@ -111,7 +110,4 @@ active — the report is informational, not a gate.
 
 ## See also
 
-- [`road-to-engineering-memory.md`](../../../agents/roadmaps/road-to-engineering-memory.md) — roadmap this guideline implements
-- [`road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md) — why content-addressed files
 - [`review-routing-data-format.md`](review-routing-data-format.md) — sibling format for ownership + bug patterns
-- [`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md) — role modes that consume these files

package/.agent-src/guidelines/agent-infra/layered-settings.md

@@ -198,4 +198,3 @@ the next explicit settings edit.
 
 - [`agent-settings.md`](../../templates/agent-settings.md) — dev-layer schema
 - [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml) — team-layer template
-- [`road-to-project-memory.md`](../../../agents/roadmaps/road-to-project-memory.md) — roadmap this guideline implements

package/.agent-src/guidelines/agent-infra/memory-access.md

@@ -9,11 +9,6 @@ package adapter (when present). The status helper
 `scripts/memory_status.py` decides which path to take and caches the
 result for the session.
 
-Referenced by
-[`road-to-agent-memory-integration.md`](../../../agents/roadmaps/road-to-agent-memory-integration.md)
-Phase 0. The retrieval contract itself lives in
-[`agent-memory/road-to-retrieval-contract.md`](../../../agents/roadmaps/agent-memory/road-to-retrieval-contract.md).
-
 ## The contract
 
 ```python
@@ -117,5 +112,3 @@ Other types remain accessible on demand via
   — the on-disk schema
 - [`../../rules/context-hygiene.md`](../../rules/context-hygiene.md)
   — token budget that `max_entries_per_task` protects
-- [`../../../agents/roadmaps/road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md)
-  — why intake is append-only JSONL with `merge=union`

package/.agent-src/guidelines/agent-infra/role-contracts.md

@@ -117,9 +117,8 @@ do not pretend verification happened.
 ## Structured mode markers
 
 Every contract output MUST begin with a one-line HTML comment so
-session captures, log scrapers, and the measurement hook in
-[`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md#phase-4--measurement-hook-closes-q2-of-master-frame)
-can count contract-conformant outputs per mode:
+session captures, log scrapers, and the measurement hook can count
+contract-conformant outputs per mode:
 
 ```
 <!-- role-mode: developer | contract: goal,plan,changes,tests,open-questions -->
@@ -206,6 +205,5 @@ finding. See the Q4 rule in `road-to-personas.md`.
 
 ## See also
 
-- [`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md) — roadmap this guideline implements
 - [`output-patterns.md`](output-patterns.md) — generic output conventions modes inherit
 - [`agent-interaction-and-decision-quality.md`](agent-interaction-and-decision-quality.md) — how modes interact with the numbered-options protocol

package/.agent-src/guidelines/agent-infra/self-improvement-pipeline.md

@@ -129,7 +129,6 @@ unreviewed upstream changes is not.
 
 ## See also
 
-- [`road-to-curated-self-improvement.md`](../../../agents/roadmaps/road-to-curated-self-improvement.md) — roadmap this guideline implements
 - [`proposal.example.md`](../../templates/agents/proposal.example.md) — the template every proposal derives from
 - [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — Understand → Research → Draft sequence used inside Stage 3
 - [`preservation-guard`](../../rules/preservation-guard.md) — invoked by the gate to check replacement proposals

package/.agent-src/guidelines/php/patterns/strategy.md

@@ -15,6 +15,25 @@ Select the implementation based on context (config, user input, enum value).
 - Notification channels (Email, SMS, Push)
 - Import parsers (JSON, XML, CSV)
 
+## Sniff test — when an enum/string discriminator wants to become a Strategy
+
+Run these three questions **before** writing a second `match`/`switch` arm,
+a second `if/elseif` branch, or a second hardcoded class per provider/type.
+Two "yes" answers → extract Strategy + Registry. Three "yes" → it is
+already overdue.
+
+1. **Same-shape branches?** Do two or more branches/classes implement the
+   *same operation* on the *same data*, differing only in provider-specific
+   details (URL, field mapping, credentials, response parsing)?
+2. **Closed-list edits?** Adding a new case requires editing an enum, a
+   `match` block, an allowlist constant, *and* a service class — i.e. the
+   change is mechanical but spans ≥3 files?
+3. **Discriminator leakage?** Does the discriminator (`Type::FOO`,
+   `'stripe'`, an `is_csv()` check) appear in ≥3 places that should not
+   have to know about `FOO` specifically?
+
+If yes → see *Refactoring recipe* below.
+
 ## Example
 
 ```php
@@ -62,8 +81,167 @@ enum DiscountType: string
 }
 ```
 
+## Refactoring recipe — from discriminator to Strategy
+
+Two anti-patterns appear in real codebases and both refactor into the same
+Strategy + Registry shape. Each step is a separate commit so reviewers can
+follow the safety chain.
+
+### Sub-pattern A — *hardcoded single provider per class*
+
+Each provider gets its own `FooImportService`, `FooJob`, `FooCommand`,
+and every method body repeats `Provider::FOO->value` or
+`Provider::FOO->getId()`. Adding a new provider means copy-pasting an
+entire class tree.
+
+```php
+// Before — one class per provider, discriminator hardcoded.
+final class StripeImportService
+{
+    public function id(): int     { return Provider::STRIPE->getId(); }
+    public function name(): string { return Provider::STRIPE->value; }
+    public function import(): void { /* Stripe-specific logic */ }
+}
+
+final class PaypalImportService
+{
+    public function id(): int     { return Provider::PAYPAL->getId(); }
+    public function name(): string { return Provider::PAYPAL->value; }
+    public function import(): void { /* PayPal-specific logic */ }
+}
+```
+
+```php
+// After — one interface, N strategies, one registry.
+interface ImportStrategy
+{
+    public function provider(): Provider;
+    public function import(): void;
+}
+
+final class StripeImport implements ImportStrategy
+{
+    public function provider(): Provider { return Provider::STRIPE; }
+    public function import(): void       { /* Stripe-specific logic */ }
+}
+// ...PaypalImport implements ImportStrategy similarly.
+```
+
+Recipe (one commit per step):
+
+1. Extract the interface (`ImportStrategy`) and move one provider class
+   to implement it. Existing call sites keep using the old class.
+2. Repeat for the remaining providers — still no callers changed.
+3. Introduce the Registry (next section). Migrate call sites one by one
+   from `new StripeImportService()` to `$registry->for(Provider::STRIPE)`.
+4. Delete the old per-provider classes.
+
+### Sub-pattern B — *allowlist constant on a single coordinator*
+
+A central service holds an allowlist of supported discriminator values.
+Every new provider edits the constant *and* a method that branches on it.
+
+```php
+// Before — closed-list edit per new provider.
+final class EquipmentImportService
+{
+    private const FULL_SYNC_PROVIDERS = [
+        Provider::STRIPE,
+        Provider::PAYPAL,
+        Provider::INVOICE,
+    ];
+
+    public function supportsFullSync(Provider $p): bool
+    {
+        return in_array($p, self::FULL_SYNC_PROVIDERS, true);
+    }
+}
+```
+
+The fix is a **capability flag on the strategy interface** — the strategy
+declares its own capabilities, and the coordinator asks the strategy
+instead of consulting an allowlist.
+
+```php
+interface ImportStrategy
+{
+    public function provider(): Provider;
+    public function import(): void;
+    public function supportsFullSync(): bool;   // capability flag
+}
+```
+
+A new provider now adds itself by implementing the interface — no central
+list to edit, no in_array call to maintain. The coordinator becomes:
+
+```php
+$strategy = $registry->for($provider);
+if ($strategy->supportsFullSync()) {
+    $strategy->fullSync();
+}
+```
+
+## Registry companion
+
+A Registry resolves the discriminator → strategy lookup that previously
+lived in the `match` block. It owns the only place the enum is mapped to
+classes; everything downstream sees only the interface.
+
+```php
+final class ImportStrategyRegistry
+{
+    /** @var array<string, ImportStrategy> */
+    private array $byProvider;
+
+    /** @param iterable<ImportStrategy> $strategies */
+    public function __construct(iterable $strategies)
+    {
+        foreach ($strategies as $strategy) {
+            $this->byProvider[$strategy->provider()->value] = $strategy;
+        }
+    }
+
+    public function for(Provider $provider): ImportStrategy
+    {
+        return $this->byProvider[$provider->value]
+            ?? throw new InvalidArgumentException(
+                "No import strategy registered for {$provider->value}"
+            );
+    }
+}
+```
+
+Wire-up in Laravel — tag the strategies, inject the tag into the registry:
+
+```php
+// In a ServiceProvider::register()
+$this->app->tag([
+    StripeImport::class,
+    PaypalImport::class,
+    InvoiceImport::class,
+], 'import.strategies');
+
+$this->app->bind(
+    ImportStrategyRegistry::class,
+    fn ($app) => new ImportStrategyRegistry($app->tagged('import.strategies')),
+);
+```
+
+A new provider now adds itself by:
+
+1. Implementing `ImportStrategy`.
+2. Adding one line to the `tag()` call.
+
+No `match` block grows. No allowlist edits. No coordinator method changes.
+
 ## When NOT to Use
 
-❌ Only two cases with trivial logic — a simple `match` or ternary is enough
-❌ The "strategies" share no common interface or behavior
+❌ Only two cases with **trivial logic** — a simple `match` or ternary is
+   enough. *"Trivial"* means the two arms each fit on one line and share
+   no structural shape. Two arms that each call a method on a service
+   are not trivial — see the sniff test.
+❌ The "strategies" share no common interface or behavior — if the
+   operations differ, you do not have a Strategy candidate.
+❌ The discriminator is set once at boot and never re-evaluated — a
+   single binding in the container is simpler than a Registry.
 

package/.agent-src/personas/README.md

@@ -99,6 +99,5 @@ cast (usually Core-6 for review skills, empty for others).
 
 ## Related
 
-- [`../../agents/roadmaps/archive/road-to-personas.md`](../../agents/roadmaps/archive/road-to-personas.md) — roadmap + rationale (shipped 2026-04-22)
 - [`../guidelines/agent-infra/role-contracts.md`](../guidelines/agent-infra/role-contracts.md) — workflow modes personas compose with
 - [`../rules/artifact-drafting-protocol.md`](../rules/artifact-drafting-protocol.md) — mandatory per new persona

package/.agent-src/rules/artifact-drafting-protocol.md

@@ -39,8 +39,13 @@ If the user skips Q1 or Q5, stop and surface the ambiguity — don't guess.
 
 ## Phase B — Research
 
-Scan `.agent-src.uncompressed/` for overlap. Report the top 3-5
-most-similar artifacts and ask (numbered options):
+Run the **search protocol** from
+[`learning-to-rule-or-skill` § 4](../skills/learning-to-rule-or-skill/SKILL.md#4-check-for-overlap--search-protocol-mandatory)
+— `ls` all four surfaces (`skills/`, `rules/`, `guidelines/`, `commands/`),
+grep with **solution-words AND problem-words**, scan sub-directory
+taxonomies, then **open and skim** the 3 nearest matches. A negative grep
+alone is not proof of no overlap. Report the top 3-5 most-similar
+artifacts and ask (numbered options):
 
 - Extend an existing one?
 - Create a new one — gap is real?

package/.agent-src/rules/artifact-engagement-recording.md

@@ -0,0 +1,133 @@
+---
+type: "auto"
+alwaysApply: false
+description: "After completing a /implement-ticket or /work phase-step (refine, memory, analyze, plan, implement, test, verify, report) or full task — emit one telemetry:record call with consulted+applied artefact ids when telemetry.artifact_engagement.enabled is true"
+source: package
+---
+
+<!-- cloud_safe: noop -->
+
+# Artifact Engagement Recording
+
+Records which **skills, rules, commands, guidelines, personas** the agent
+actually consulted and applied during a `/implement-ticket` or `/work` run.
+Default-off; opt-in via `.agent-settings.yml`. Zero overhead when disabled.
+
+The schema, CLI, and storage layer are owned by
+[`scripts/telemetry/`](../../../scripts/telemetry/) and the
+`./agent-config telemetry:record` / `telemetry:status` commands shipped
+in Phase 1+2 of the
+[`road-to-artifact-engagement-telemetry`](../../../agents/roadmaps/road-to-artifact-engagement-telemetry.md)
+roadmap. This rule says **when** to call the CLI, not how the file is
+structured.
+
+## Activation gate — read settings ONCE per task, then cache
+
+Before the first `/implement-ticket` or `/work` step runs, read
+`telemetry.artifact_engagement.enabled` from `.agent-settings.yml`. Cache
+the value (and `granularity`) for the whole task.
+
+- `enabled: false` or section missing → rule is a **no-op**. Do not import
+  the script, do not open the log, do not mention recording. Skip the rest
+  of this rule.
+- `enabled: true` → continue with the cadence below.
+
+Use `./agent-config telemetry:status --format json` if the value is
+not already in working memory; the call is read-only and never touches
+the log file.
+
+## Cadence — depends on `granularity`
+
+| `granularity` | When to emit | Coalescing |
+|---|---|---|
+| `task` *(default)* | Once, when the eight-step flow ends (success, blocked, partial — any terminal state) | All consulted/applied artefacts from refine through report merged into a single event |
+| `phase-step` | At the close of each phase-step (refine, memory, analyze, plan, implement, test, verify, report) | One event per step; per-step consulted/applied lists only |
+
+Within a single boundary, **dedupe** consulted and applied lists. A skill
+consulted three times in the same boundary records once.
+
+## What counts as consulted vs applied
+
+- **`consulted`** — the agent **read** the artefact this boundary: opened
+  its `SKILL.md`, scanned its rule body, viewed its frontmatter,
+  referenced its guideline, checked its persona contract, dispatched its
+  command. Reading does not imply behaviour change.
+- **`applied`** — the artefact **influenced the output** this boundary:
+  its instructions changed how the agent answered, what code it wrote,
+  what tools it ran, or what halt surface it produced. Applied is a
+  strict subset of consulted.
+
+When in doubt → record as `consulted` only. Over-recording `applied`
+inflates the engagement signal and defeats the purpose.
+
+## What to record — id-only, no payload
+
+```bash
+./agent-config telemetry:record \
+  --task-id "$TASK_ID" \
+  --boundary task \
+  --consulted skills:php-coder \
+  --consulted skills:eloquent \
+  --consulted rules:scope-control \
+  --applied skills:php-coder \
+  --applied rules:scope-control
+```
+
+- `--task-id` — the ticket key (`PROJ-123`) for `/implement-ticket`, or a
+  short opaque slug derived from the prompt for `/work`. **Never** a
+  branch name, a file path, or a free-text title.
+- `--boundary` — `task` or `phase-step`, matching the cadence above.
+- `--consulted <kind>:<id>` — repeat per artefact. `<kind>` is one of
+  `skills`, `rules`, `commands`, `guidelines`, `personas`.
+- `--applied <kind>:<id>` — repeat per artefact actually applied.
+- Exit `0` always when disabled (silent). Exit `1` on schema validation
+  failure (rule must NOT swallow this — surface to the user). Exit `2`
+  on IO failure.
+
+## Privacy contract — what NEVER goes into a record
+
+The CLI rejects most violations on the input boundary, but the agent must
+not even attempt these:
+
+- ❌  File paths (`src/Foo.php`, `tests/...`) — id fields are
+  artefact identifiers only.
+- ❌  Source code, prompt text, ticket body, AC text.
+- ❌  Branch names, commit shas, PR numbers, URLs.
+- ❌  Secrets, env vars, credentials, customer data.
+- ❌  Free-text strings longer than 200 chars (CLI enforces; agent must
+  not generate).
+
+When in doubt → **don't record**. A missing event is cheap; a leaked
+prompt is not.
+
+## Failure modes — DO NOT block the user's task
+
+- Schema rejection (CLI exit `1`) → log the message internally, continue
+  the user's task. Do **not** halt the dispatch loop.
+- IO failure (CLI exit `2`) → same. The telemetry is **observation**, not
+  a delivery requirement.
+- Settings malformed → already handled by the CLI: it falls back to
+  disabled and exits `0`. Agent treats it as "disabled this task".
+
+The only error the agent surfaces is when the user explicitly asked for
+recording (`telemetry:status` confirms enabled) but no event reached the
+log — that is a real bug, not a swallowed error.
+
+## What this rule does NOT do
+
+- Run when `enabled: false` (cost floor is zero — see
+  [`tests/telemetry/test_cost_floor.py`](../../../tests/telemetry/test_cost_floor.py)).
+- Track the agent's tool calls, file reads, or token spend — that is
+  out of scope, see the roadmap's "out-of-scope" section.
+- Decide retirement. Phase 4's aggregator + report renderer are the only
+  consumers that may interpret the JSONL.
+- Run on cloud surfaces (Claude.ai Web, Skills API). The
+  `cloud_safe: noop` marker keeps it inert there.
+
+## See also
+
+- [`road-to-artifact-engagement-telemetry`](../../../agents/roadmaps/road-to-artifact-engagement-telemetry.md) — phase contract
+- [`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md) — recording contract details
+- [`/implement-ticket`](../commands/implement-ticket.md) and [`/work`](../commands/work.md) — boundary points where this rule fires
+- [`scripts/telemetry/`](../../../scripts/telemetry/) — engine source
+- [`agent-settings`](../templates/agent-settings.md) — `telemetry.artifact_engagement.*` reference

package/.agent-src/rules/ask-when-uncertain.md

@@ -10,6 +10,20 @@ source: package
 **When in doubt, ask the user.** Do not guess, assume, or improvise.
 Asking one question too many is always better than a wrong assumption.
 
+## Iron Law — one question per turn, ALWAYS
+
+```
+ONE QUESTION PER TURN. NO EXCEPTIONS.
+ASK. WAIT FOR THE ANSWER. THEN ASK THE NEXT.
+```
+
+This is absolute. Not a default, not a guideline, not "usually".
+Every turn that contains a question contains **exactly one** question.
+Even if the questions look trivial. Even if they look independent.
+Even if they would fit on one screen. Even if batching "feels more
+efficient". Full self-check, ordering, and handoff rules under
+[How to ask](#how-to-ask).
+
 ## When to ask
 
 - Requirement is ambiguous or could be interpreted multiple ways
@@ -42,22 +56,13 @@ makes the answer unambiguous, proceed — but state the assumption explicitly.
 
 Be specific. Present numbered options (per `user-interaction`). Keep it short.
 
-### The Iron Law — one question per turn, ALWAYS
-
-```
-ONE QUESTION PER TURN. NO EXCEPTIONS.
-ASK. WAIT FOR THE ANSWER. THEN ASK THE NEXT.
-```
-
-This is absolute. Not a default, not a guideline, not "usually". Every
-turn that contains a question contains **exactly one** question. Even
-if the questions look trivial. Even if they look independent. Even if
-they would fit on one screen. Even if batching "feels more efficient".
+The Iron Law (one question per turn) is at the top of this file.
+This section adds the rationale, self-check, and ordering.
 
 The user must never have to track sub-numbers, scroll through stacked
 option blocks, or split their reply across multiple questions. One
-question, numbered options (per `user-interaction`), one short answer,
-next turn.
+question, numbered options (per `user-interaction`), one short
+answer, next turn.
 
 Rationale — why even "trivial" batches fail: