@event4u/agent-config 1.13.0 → 1.14.0

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
+- [`agents/contexts/artifact-engagement-flow.md`](../../../agents/contexts/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:
 

package/.agent-src/rules/augment-portability.md

@@ -75,6 +75,14 @@ package repo, in consumer projects the scripts live under
 | `python3 .augment/scripts/update_roadmap_progress.py` | `./agent-config roadmap:progress` |
 | `python3 .augment/scripts/update_roadmap_progress.py --check` | `./agent-config roadmap:progress-check` |
 | `bash scripts/first-run.sh` | `./agent-config first-run` |
+| `PYTHONPATH=… python3 -m implement_ticket` | `./agent-config implement-ticket` |
+| `python3 scripts/memory_lookup.py` | `./agent-config memory:lookup` |
+| `python3 scripts/memory_signal.py` | `./agent-config memory:signal` |
+| `python3 scripts/memory_hash.py` | `./agent-config memory:hash` |
+| `python3 scripts/check_memory.py` | `./agent-config memory:check` |
+| `python3 scripts/check_memory_proposal.py` | `./agent-config memory:check-proposal` |
+| `python3 scripts/check_proposal.py` | `./agent-config proposal:check` |
+| `python3 scripts/refine_ticket_detect.py` | `./agent-config refine-ticket:detect` |
 
 Commands not covered by the CLI stay as direct script invocations
 (e.g. `bash scripts/compress.sh --sync`) — maintainer-only, not

package/.agent-src/rules/autonomous-execution.md

@@ -0,0 +1,158 @@
+---
+type: "always"
+description: "Suppress trivial workflow questions and act on the obvious next step; defers to non-destructive-by-default for the safety floor; never commit and never ask about committing except via /commit-in-chunks or explicit user instruction"
+alwaysApply: true
+source: package
+---
+
+# Autonomous Execution
+
+User's time is the scarce resource. Trivial workflow questions are
+noise. Defines **trivial** (just act), **blocking** (still ask), the
+**hard floor** (always ask, no override), and the **commit default**
+(never commit, never ask — review-first by design).
+
+## Hard Floor — see [`non-destructive-by-default`](non-destructive-by-default.md)
+
+Universal safety floor (production-branch merges, deploys, pushes,
+prod data/infra, whimsical bulk deletions, and commits containing
+bulk deletions or infra changes) is governed by the canonical
+[`non-destructive-by-default`](non-destructive-by-default.md) rule.
+
+Applies regardless of `personal.autonomy`, a standing autonomy
+directive (anchor list in [Opt-in detection](#opt-in-detection--match-by-intent-not-exact-string)),
+or any roadmap authorization. Nothing in **this** rule lifts it. If a
+trigger from that rule fires, stop and ask — every section below
+assumes the floor has cleared.
+
+## Setting — `personal.autonomy`
+
+| Value | Behavior |
+|---|---|
+| `on` | Suppress trivial questions. Act on obvious next step. Still ask on blocking decisions; ALWAYS ask on Hard-Floor triggers. |
+| `off` | Ask trivial questions too. Use to check in on each workflow step. |
+| `auto` (default) | Like `off` until user expresses "stop asking, just work" — then `on` for the rest of the chat. See **Opt-in detection** below; match by **intent**, not exact string. The flip never lifts the Hard Floor. |
+
+Read once on first turn (per [`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
+and cache. Missing key → treat as `on`.
+
+## Opt-in detection — match by intent, not exact string
+
+In `auto`, flip to `on` for the rest of the chat when the user expresses
+**"stop asking on trivial steps, just work"**. Recognize the **intent**,
+not the literal substring — semantic equivalent in either language.
+
+Anchor examples (illustrative, not exhaustive):
+
+- DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
+- EN: "work autonomously" · "don't ask" · "just do it"
+
+Litmus test: standing permission to skip trivial questions? → flip.
+Single-decision delegation ("you decide for this step") → handle that
+step, do **not** flip standing mode.
+
+### Speech-act check — meta-instruction, not content
+
+Before flipping, verify the phrase is **addressed to the agent as
+guidance about how to work**, not a literal substring inside another
+instruction. Do **not** flip when the phrase is:
+
+- **Content / copy** — "Put the slogan 'just do it' on the landing page."
+- **Quote / reference** — "Nike's tagline is 'just do it' — write a blog post."
+- **Subject of a request** — "Write docs about the 'work autonomously' modes."
+- **Code / data** — string literals, fixtures, translations, JSON.
+- **About a third party** — "My colleague works autonomously."
+- **Question / hypothetical** — "Should I set `don't ask` as the default?"
+
+Heuristic: strip quotes, code blocks, embedded content. Read what's
+**left**. Still a directive to the agent about its working style →
+flip. Otherwise → don't.
+
+Opt-out (reversed intent) flips back to `off`:
+
+- DE: "frag mich wieder" · "frag mich erst" · "stop autonomous mode"
+- EN: "ask me first" · "ask me again" · "stop being autonomous"
+
+Same speech-act check applies.
+
+Counter-examples — do **not** flip on meta-questions, self-descriptions,
+or one-shot delegations: "why don't you ask that yourself?", "I'm
+working autonomously right now", "can you decide that yourself?".
+
+In doubt → keep current mode, no speculative flips.
+
+## Trivial — JUST ACT, do not ask
+
+Examples (matches `personal.autonomy: on` or `auto`-after-opt-in):
+
+- "Step 2 or Step 3?" — pick the obvious next roadmap step; if blocked, name the blocker, otherwise go.
+- "Commit now or after the next change?" — answered by the commit-default below.
+- "How should I split the commits?" — never asked; either `/commit-in-chunks` was invoked (split + commit) or it wasn't (don't commit).
+- "Run linter / tests now or later?" — `verify-before-complete` decides; act.
+- "Found 3 follow-ups — fix all or stop?" — if within scope and minimal-safe-diff allows, fix; if scope expands, stop and surface as list.
+- "Filename `X.md` or `Y.md`?" when one matches convention — pick convention-matching one.
+- "Verification table or paragraph?" — pick whichever fits; format isn't a decision worth a turn.
+- "Show me a diff before regenerating output from a tracked source?"
+  — compression, code-gen, formatter passes, lock-file rebuilds — run
+  it and report the result. Reversibility comes from the source, not
+  from per-file confirmation. See [`non-destructive-by-default`](non-destructive-by-default.md#not-in-scope--deterministic-regeneration)
+  § Not in scope.
+
+`personal.autonomy: off`: ask these. `on` or `auto`-after-opt-in: act.
+
+## Blocking — STILL ASK regardless of `personal.autonomy`
+
+Beyond the Hard Floor, the autonomy setting also never overrides:
+
+- **Vague-request triggers** in [`ask-when-uncertain`](ask-when-uncertain.md) — ambiguous stays ambiguous; pick-one-and-pray is wrong.
+- **Architectural / structural choices** the codebase hasn't settled (multi-stack picks, library introductions).
+- **Security-sensitive paths** — see [`security-sensitive-stop`](security-sensitive-stop.md).
+- **Scope expansion** beyond stated task — see [`scope-control`](scope-control.md).
+- **Remote-state ops** — push, merge, rebase, force-push, branch create/delete/switch, PR create/close/retarget, tag/release. Permission-gated by [`scope-control`](scope-control.md); the prod-trunk and deploy-tied subset is governed by [`non-destructive-by-default`](non-destructive-by-default.md).
+- **Destructive ops** — see [`non-destructive-by-default`](non-destructive-by-default.md) for the full taxonomy (whimsical bulk deletions, content destruction, commits containing bulk deletions or infra changes).
+
+In doubt → blocking. Ask.
+
+## Commit policy — see [`commit-policy`](commit-policy.md)
+
+Committing is governed by [`commit-policy`](commit-policy.md), which
+applies regardless of `personal.autonomy`. Summary:
+
+- NEVER commit unless user said so this turn, a commit command was
+  invoked, a standing instruction is active, or the roadmap authorizes it.
+- NEVER ask about committing.
+- In autonomous mode, the **only** permitted commit-related question
+  is the one-shot pre-scan ask at the start of roadmap execution.
+
+Push, merge, rebase, branch creation, PR ops, tags remain
+permission-gated per [`scope-control`](scope-control.md#git-operations--permission-gated).
+
+## Failure modes
+
+- Asking "Step 2 or Step 3?" when the roadmap orders them.
+- "Should I run the CI checks?" — `verify-before-complete` decides; act.
+- "Do we want to commit this?" — no, by default. Don't ask.
+- Numbered-options block whose only difference is sequencing ("A then B" vs "B then A") with no real trade-off.
+- Asking after user already issued a standing autonomy directive earlier (cache the opt-in for `auto`).
+
+For Hard-Floor failure modes (treating autonomy as cover for a
+floor-crossing action, reading a roadmap step as deploy authorization,
+refusing task-aligned WIP deletions, committing bulk-deletion / infra
+diffs without surfacing them) see
+[`non-destructive-by-default`](non-destructive-by-default.md#failure-modes).
+
+## Cloud Behavior
+
+Settings reads degrade gracefully on cloud platforms (no
+`.agent-settings.yml`). Treat as `personal.autonomy: on` — user had to
+deliberately ship a custom skill bundle and is unlikely to want
+trivial-question friction.
+
+## See also
+
+- [`non-destructive-by-default`](non-destructive-by-default.md) — universal safety floor; never overridden by autonomy
+- [`scope-control`](scope-control.md) — git-ops permission gate (push/merge/branch/PR/tag stays explicit)
+- [`ask-when-uncertain`](ask-when-uncertain.md) — vague-request triggers that always require asking
+- [`direct-answers`](direct-answers.md) — Iron Laws on brevity and no-flattery (this rule extends to no-trivial-questions)
+- [`/commit-in-chunks`](../commands/commit-in-chunks.md) — auto-split and commit without confirmation
+- [`/commit`](../commands/commit.md) — split and commit with confirmation