@event4u/agent-config 1.15.0 → 1.16.0

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -101,7 +101,7 @@ These reference Augment-only mechanics — model identity in Augment's
 system prompt, Augment's `/slash` command surface, and the Augment
 onboarding flow gated by `.agent-settings.yml`.
 
-`model-recommendation`, `onboarding-gate`, `slash-commands`.
+`model-recommendation`, `onboarding-gate`, `slash-command-routing-policy`.
 
 ### Skill-routing only (1)
 

package/docs/contracts/load-context-schema.md

@@ -0,0 +1,186 @@
+---
+stability: beta
+---
+
+# `load_context:` Frontmatter Schema
+
+> **Audience:** rule authors and reviewers who want to keep an Always-rule
+> small while making deeper reasoning available on demand.
+> **Linter:** `scripts/lint_load_context.py` (run via `task lint-load-context`).
+> **Companion:** [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) —
+> hierarchy that decides *which* rule wins when several fire on the same turn.
+
+This contract defines the frontmatter convention by which a rule (or
+another context) declares the deeper reading material it relies on.
+The convention is **lazy by default**: declared entries are *available
+to load* when the situation demands them, never auto-loaded into every
+turn.
+
+## Schema
+
+Two keys, both optional, both top-level frontmatter:
+
+```yaml
+---
+type: "always"
+description: "..."
+load_context:                # lazy — on-demand reference list
+  - .agent-src.uncompressed/contexts/<file>.md
+  - agents/contexts/<file>.md
+load_context_eager:          # opt-in eager — auto-loaded on rule fire
+  - .agent-src.uncompressed/contexts/<file>.md
+---
+```
+
+| Key | Loading | When to use |
+|---|---|---|
+| `load_context:` | **Lazy.** The agent reads the entry only when the rule's reasoning needs it. | Default. Use for everything that is "available knowledge" rather than "on every turn". |
+| `load_context_eager:` | **Eager.** The entry is concatenated into the active context whenever the rule fires. | Only when the deeper material is needed *every single time* the rule fires. Counts against the combined char budget. |
+
+**No default eager-load.** A rule with `load_context:` only does **not**
+auto-load anything; the agent decides per turn. Eager loading is
+opt-in and budget-gated.
+
+## Path rules
+
+- Paths are repo-root relative.
+- Paths MUST end in `.md`.
+- Allowed roots: `.agent-src.uncompressed/contexts/`, `agents/contexts/`,
+  `.agent-src/contexts/` (compressed mirror). Any other root → linter
+  error.
+- A rule MAY reference contexts under either tree, but a
+  `.agent-src.uncompressed/` rule SHOULD NOT eager-load an
+  `agents/contexts/` file (project-local leak into shared package).
+  Linter warns on this combination.
+- A context file may itself declare `load_context:` (chain reasoning).
+  The linter rejects cycles.
+
+## Subdirectory conventions
+
+Subdirectories under `contexts/` are **conventional, not enforced**.
+The linter only validates the root prefix; subdirectory layout is a
+documentation contract for human reviewers.
+
+Two canonical subdirectories are in production:
+
+| Subdir | Holds | First consumer |
+|---|---|---|
+| `contexts/execution/` | runtime decision logic, mechanics, and examples for execution-time rules (autonomy detection, verification mechanics, etc.) | `autonomous-execution` (Phase 2 of `road-to-pr-34-followups`) |
+| `contexts/authority/` | mechanics behind authority gates — what makes commits, scope changes, and git ops legal vs. illegal | `commit-policy` and `scope-control` (Phase 6 of `road-to-pr-34-followups`) |
+
+A third subdirectory, `contexts/communication/`, was proposed by the
+PR #34 round-6 review for user-interaction and language-and-tone
+mechanics. It is **not yet created** — the anti-speculation guard in
+Phase 6 forbids creating a context root before its triggering rule
+exists. Add it the same turn as the first migrating rule, not before.
+
+A new subdirectory is justified when:
+
+- A second rule needs to share contexts with the first one, AND
+- The contexts have a coherent topic (execution, authority, communication, …), AND
+- The triggering rule and its content move at the same time
+  (no empty subdir reservations).
+
+Single-rule contexts that don't fit one of the canonical topics live
+directly under `contexts/` (see `contexts/model-recommendations.md`,
+`contexts/skills-and-commands.md`).
+
+## Combined char-budget guard
+
+`load_context_eager:` triggers a budget check:
+
+```
+chars(rule.md) + sum(chars(eager_target.md) for each entry) ≤ rule_cap
+```
+
+`rule_cap` is the per-rule budget from
+[`road-to-rebalancing.md`](../../agents/roadmaps/road-to-rebalancing.md)
+§ Target architecture:
+
+- Always rule: 2,500
+- Auto rule: 4,000
+- Safety rule (`type: "always"` AND covers Hard-Floor topics): 5,000
+
+Linter computes the rule's class from frontmatter `type:` and the
+hard-floor allowlist (`non-destructive-by-default`,
+`security-sensitive-stop`). Exceeding the cap → linter error.
+
+Lazy `load_context:` does **not** count against the budget — by
+definition it is not loaded into every turn.
+
+## Public-vs-internal leak
+
+A rule shipped to consumers (`.agent-src.uncompressed/rules/`) may
+declare `load_context:` entries pointing at:
+
+- `.agent-src.uncompressed/contexts/` — public, OK.
+- `agents/contexts/` — package-internal, **lint warning** (the entry
+  will not exist in consumer projects).
+
+Project-local rules may reference either. The linter classifies by
+the rule's tree, not by the target's tree.
+
+## No circular references
+
+A `load_context:` graph that cycles fails the linter. Cycles are
+defined across both `load_context:` and `load_context_eager:` edges.
+
+## Examples
+
+### Real consumer — `autonomous-execution`
+
+`.agent-src.uncompressed/rules/autonomous-execution.md` is the first
+production rule to declare `load_context:`. Its frontmatter:
+
+```yaml
+---
+type: "auto"
+description: "Deciding whether to ask the user or just act on a workflow step — trivial-vs-blocking classification, autonomy opt-in detection, commit default; defers to non-destructive-by-default for the Hard Floor"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/execution/autonomy-detection.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-mechanics.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-examples.md
+---
+```
+
+Three lazy-loaded contexts, no `load_context_eager:`. The agent reads
+each context only when the corresponding section of the slim rule
+points at it (the rule body cites the same paths in prose so the
+load is intent-driven, not blanket).
+
+Pattern proven by this consumer:
+
+- **Slim the rule to obligations only** — the 192-line pre-split
+  source dropped to 119 lines (≤ 120 target met) by extracting LOGIC
+  (detection algorithm), MECHANICS (setting table, cloud behavior),
+  and EXAMPLES (anchor phrases, worked cases, failure modes) into
+  three separate context files.
+- **Cite, don't duplicate** — the slim rule contains zero
+  algorithm/mechanics/example prose; everything moved was physically
+  removed (verified by Phase 2.5 obligation diff:
+  [`agents/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md`](../../agents/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md)).
+- **Lazy by default** — no eager-load is declared; the budget guard
+  is therefore a no-op for this rule.
+
+`task lint-load-context` reports **1 declarer**, all paths resolve,
+no cycles.
+
+## Stability
+
+`beta` — schema is settled and serves one production rule
+(`autonomous-execution`). A breaking schema change is a SemVer-minor
+pre-1.0 bump. Adding a new optional key is non-breaking. The first
+consumer surfaced no schema gaps; the next migration batch (roadmap
+`road-to-pr-34-followups` Phase 6 — `commit-policy`, `scope-control`,
+`verify-before-complete`) is the next stress test.
+
+## Cross-references
+
+- [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) — which
+  rule wins on conflict; this schema is orthogonal (depth, not
+  priority).
+- [`rule-interactions.yml`](rule-interactions.yml) — pairwise rule
+  interaction matrix.
+- [`STABILITY.md`](STABILITY.md) — beta-tag implications.

package/docs/contracts/rule-interactions.yml

@@ -30,6 +30,9 @@ rules:
   - commit-policy
   - ask-when-uncertain
   - verify-before-complete
+  - agent-authority
+  - language-and-tone
+  - direct-answers
 
 pairs:
 
@@ -140,3 +143,96 @@ pairs:
     evidence:
       - .agent-src.uncompressed/rules/commit-policy.md#the-iron-law
       - .agent-src.uncompressed/rules/autonomous-execution.md#commit-policy--see-commit-policy
+
+  - id: authority-x-ndd
+    rules: [agent-authority, non-destructive-by-default]
+    relation: defers_to
+    conflict: >-
+      Both rules speak to "may the agent do this autonomously?" — the
+      Priority Index points to the Hard Floor as Band 1.
+    resolution: >-
+      `agent-authority` is a router, never a source of truth. The Hard
+      Floor's Iron Law lives verbatim in `non-destructive-by-default`
+      and wins every conflict. The index points; it never restates.
+    evidence:
+      - .agent-src.uncompressed/rules/agent-authority.md#index-rules
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+
+  - id: authority-x-scope-control
+    rules: [agent-authority, scope-control]
+    relation: defers_to
+    conflict: >-
+      Permission Gate questions (push, branch, PR, architectural change)
+      surface during routine work — the index labels Band 2.
+    resolution: >-
+      The Priority Index routes to `scope-control` for git-shape and
+      scope-expansion decisions. Index never narrows or weakens the
+      gate; canonical rule wins on any wording divergence.
+    evidence:
+      - .agent-src.uncompressed/rules/agent-authority.md#index-rules
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+
+  - id: authority-x-commit-policy
+    rules: [agent-authority, commit-policy]
+    relation: defers_to
+    conflict: >-
+      The "about to commit" decision arises — the index labels it Band 3
+      (Commit Default = never, with four exceptions).
+    resolution: >-
+      `commit-policy` Iron Law is canonical. The Priority Index points
+      to it; it does not enumerate the four exceptions itself. Future
+      edits to commit-policy do not require Index updates unless the
+      band ordering changes.
+    evidence:
+      - .agent-src.uncompressed/rules/agent-authority.md#index-rules
+      - .agent-src.uncompressed/rules/commit-policy.md#exceptions--when-committing-is-allowed
+
+  - id: scope-x-commit-policy
+    rules: [scope-control, commit-policy]
+    relation: narrows
+    conflict: >-
+      `scope-control` § "Git operations" forbids committing without
+      explicit permission as one of several git-op gates; `commit-policy`
+      narrows the commit case to a never-ask default with four named
+      exceptions.
+    resolution: >-
+      `commit-policy` is the narrower, canonical rule for the commit
+      sub-case. `scope-control` continues to govern push, branch, PR,
+      tag operations. On commit specifics, defer to `commit-policy`;
+      on other git ops, defer to `scope-control`.
+    evidence:
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+      - .agent-src.uncompressed/rules/commit-policy.md#the-iron-law
+
+  - id: ask-x-direct-answers
+    rules: [ask-when-uncertain, direct-answers]
+    relation: complements
+    conflict: >-
+      A vague request triggers `ask-when-uncertain` (must ask), but
+      `direct-answers` Iron Law 3 (brevity by default) discourages
+      overlong replies; could read as tension when the question needs
+      framing.
+    resolution: >-
+      Both rules apply. `ask-when-uncertain` decides *whether* to ask
+      and demands one question per turn with numbered options.
+      `direct-answers` shapes *how* the question reads — no flattery,
+      no padding, shortest form that fully states the choice.
+    evidence:
+      - .agent-src.uncompressed/rules/ask-when-uncertain.md#iron-law--one-question-per-turn-always
+      - .agent-src.uncompressed/rules/direct-answers.md#iron-law-3--brevity-by-default
+
+  - id: language-x-direct-answers
+    rules: [language-and-tone, direct-answers]
+    relation: complements
+    conflict: >-
+      User writes German; agent must mirror language AND avoid flattery,
+      invented facts, padding. Both rules speak to reply shape.
+    resolution: >-
+      `language-and-tone` decides the language token (mirror user's last
+      chat message); `direct-answers` decides content discipline (no
+      flattery, verified facts, brevity). They compose: a brief, direct,
+      flattery-free reply in the user's language. Neither weakens the
+      other.
+    evidence:
+      - .agent-src.uncompressed/rules/language-and-tone.md#iron-law--mirror-the-users-language-always
+      - .agent-src.uncompressed/rules/direct-answers.md#iron-law-1--no-flattery

package/docs/contracts/rule-priority-hierarchy.md

@@ -0,0 +1,87 @@
+---
+stability: beta
+---
+
+# Rule Priority Hierarchy
+
+> **Audience:** anyone reading or editing `.agent-src.uncompressed/rules/*.md`,
+> or trying to predict which rule wins when several fire on the same turn.
+> **Machine-readable counterpart:** [`rule-interactions.yml`](rule-interactions.yml)
+> (linted by `scripts/lint_rule_interactions.py`).
+> **Diagram + pair-by-pair narrative:** [`rule-interactions.md`](rule-interactions.md).
+
+This document is the **ordered list** view. The matrix files describe
+how *pairs* of rules interact; this file states **which band wins**
+when the bands themselves disagree.
+
+## The four-line principle
+
+```
+Safety beats autonomy.
+Scope beats helpfulness.
+Verification beats completion.
+User intent beats command suggestion.
+```
+
+Every band below is a concrete instance of one of those four lines.
+When in doubt, walk the list top-down and stop at the first band that
+fires — that band's canonical rule decides the turn.
+
+## The ordered list
+
+| Band | Rule | What it gates | Lifts under |
+|---|---|---|---|
+| 1 | [`non-destructive-by-default`](../../.agent-src.uncompressed/rules/non-destructive-by-default.md) | Prod-trunk merge · deploy · push · prod data/infra · whimsical bulk deletion · bulk-deletion or infra commit | **Never.** Explicit user confirmation *this turn* only. |
+| 2 | [`security-sensitive-stop`](../../.agent-src.uncompressed/rules/security-sensitive-stop.md) | Auth · billing · tenant boundaries · secrets · file uploads · webhooks · public endpoints | Threat-model pass completed and recorded *before* the edit. |
+| 3 | [`scope-control`](../../.agent-src.uncompressed/rules/scope-control.md) | Git ops (branch · PR · tag · push · merge · rebase) · architectural changes · new libraries · scope expansion | Explicit user permission *this turn* or unrevoked standing instruction. |
+| 4 | [`ask-when-uncertain`](../../.agent-src.uncompressed/rules/ask-when-uncertain.md) | Ambiguous requirements · vague-request triggers · fenced steps | Concrete evidence resolves the ambiguity, **or** user answers the single question. |
+| 5 | [`commit-policy`](../../.agent-src.uncompressed/rules/commit-policy.md) | Any `git commit` | Four exceptions only — explicit "commit now", standing instruction, `/commit*` invocation, roadmap authorization. |
+| 6 | [`verify-before-complete`](../../.agent-src.uncompressed/rules/verify-before-complete.md) | "Done" / "complete" claims · suggestions to commit, push, or PR | Fresh verification evidence in *this* message. |
+| 7 | [`autonomous-execution`](../../.agent-src.uncompressed/rules/autonomous-execution.md) | Trivial-vs-blocking classification · autonomy opt-in detection | Per-step decision; never above bands 1–6. |
+| 8 | [`command-suggestion-policy`](../../.agent-src.uncompressed/rules/command-suggestion-policy.md) | Surfacing slash-command matches as numbered options | User always picks; nothing auto-executes. |
+| 9 | [`language-and-tone`](../../.agent-src.uncompressed/rules/language-and-tone.md) | First-token language of every reply · `.md` always English | Mirror the user's last chat message — no momentum exception. |
+
+**Read direction:** top-to-bottom is *priority on conflict*, not chronology.
+A turn typically touches several bands at once; the hierarchy decides
+which one's Iron Law gets the final say.
+
+## Index rules
+
+- **Higher band wins.** A band-3 permission does not lift band-1; a band-5
+  commit exception does not lift band-3. Each band's "Lifts under" column
+  is its own escape hatch and only its own.
+- **No band restates an Iron Law.** Iron Laws live verbatim in the
+  canonical rule files. This hierarchy points; it does not paraphrase.
+- **Bands 1–2 are *Hard Floors*.** No autonomy setting, no roadmap step,
+  no standing instruction lifts them. See
+  [`agent-authority`](../../.agent-src.uncompressed/rules/agent-authority.md)
+  § Index rules for the matching authority statement.
+- **Unsure → ask.** [`ask-when-uncertain`](../../.agent-src.uncompressed/rules/ask-when-uncertain.md)
+  is the universal escape hatch when the band is unclear.
+
+## Worked examples
+
+| Situation | Bands that fire | Winner | Why |
+|---|---|---|---|
+| Standing autonomy + roadmap step says "merge to `main`" | 1, 7 | **1** | Hard Floor predates and outranks autonomy; surface the merge, ask. |
+| `/commit-in-chunks` on a diff that removes a directory | 1, 5 | **1** | Commit exception authorizes *commits*, not *bulk deletions*. Confirm diff this turn. |
+| User asks "improve this" with no metric named | 4, 7 | **4** | Vague-request trigger fires before any autonomy decision; ask the one clarifying question. |
+| Editing `app/Auth/PasswordReset.php` mid-feature | 2, 7 | **2** | Security-sensitive surface stops the edit until threat-model is recorded. |
+| Agent about to claim "ready to merge" with no fresh test output | 5, 6 | **6** | Verification gate fires before the commit/push question is even valid. |
+| User types free-form prompt that matches `/refine-ticket` | 8, 9 | **8 + 9** | Suggestion runs as numbered options, mirrored to user's language. No conflict. |
+
+## Cross-references
+
+- [`agent-authority`](../../.agent-src.uncompressed/rules/agent-authority.md) — the four-band authority router (bands 1–3 + 7 of this hierarchy).
+- [`rule-interactions.md`](rule-interactions.md) — pairwise interaction narrative + Mermaid diagram.
+- [`rule-interactions.yml`](rule-interactions.yml) — machine-readable, CI-linted matrix.
+- [`STABILITY.md`](STABILITY.md) — what the `stability: beta` tag means for breaking changes.
+
+## Stability
+
+`beta` — the band ordering and four-line principle are settled, but
+the *worked examples* and the inclusion of band 8 (`command-suggestion-policy`)
+in the public hierarchy have not yet shipped through one major release.
+A breaking change to the band ordering is a SemVer-minor-pre-1.0 bump
+or a SemVer-major bump after 1.0. Adding a row, refining a "Lifts under"
+clause, or expanding the worked-examples table is non-breaking.

package/docs/contracts/ui-track-flow.md

@@ -334,5 +334,5 @@ suite asserts every `BLOCKED` path has a matching declaration.
   GT-U15 (preview render failure).
 - [`existing-ui-audit` SKILL](../../.agent-src.uncompressed/skills/existing-ui-audit/SKILL.md)
   — producer of `state.ui_audit`.
-- [`ui-audit-before-build` rule](../../.agent-src.uncompressed/rules/ui-audit-before-build.md)
+- [`ui-audit-gate` rule](../../.agent-src.uncompressed/rules/ui-audit-gate.md)
   — the always-on rule that mirrors the audit gate at the agent layer.

package/docs/customization.md

@@ -58,6 +58,20 @@ those sections.
 | `chat_history.max_size_kb` | per profile | Max file size before overflow handling (see matrix below). |
 | `chat_history.on_overflow` | per profile | `rotate` drops oldest, `compress` marks for summarization (see matrix below). |
 | `onboarding.onboarded` | `false` | Whether `/onboard` has run. The `onboarding-gate` rule prompts for `/onboard` while this is `false`. |
+| `ai_council.enabled` | `false` | Master switch for the `/council` command. Even when enabled, every consultation asks before spending tokens. |
+| `ai_council.members.<provider>.enabled` | `false` | Per-provider opt-in (`anthropic`, `openai`). Tokens live in `~/.config/agent-config/<provider>.key` (mode 0600), never in this file. |
+| `ai_council.members.<provider>.model` | per provider | Which model the provider sends the query to (e.g. `claude-sonnet-4-5`, `gpt-4o`). |
+| `ai_council.cost_budget.max_input_tokens` | `50000` | Hard cap on summed input tokens per `/council` invocation. |
+| `ai_council.cost_budget.max_output_tokens` | `20000` | Hard cap on summed output tokens per `/council` invocation. |
+| `ai_council.cost_budget.max_calls` | `10` | Maximum council members per invocation. |
+| `ai_council.cost_budget.max_total_usd` | `0.0` | Per-invocation USD ceiling. `0` disables (token caps still apply). |
+| `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.config/agent-config/council-spend.jsonl` (mode 0600). |
+
+Council API tokens are installed via `./agent-config keys:install-anthropic`
+and `./agent-config keys:install-openai` — they prompt on `/dev/tty`, write to
+`~/.config/agent-config/<provider>.key` with mode `0600`, and never accept env
+vars. The `/council` command refuses to run if the key file's permissions
+drift.
 
 ### Cost profiles
 

package/docs/end-to-end-walkthroughs.md

@@ -0,0 +1,165 @@
+# End-to-end walkthroughs
+
+Four cycle-by-cycle traces of the engine commands — backend ticket,
+free-form prompt, UI track, and a blocked path. Each walkthrough cites
+a checked-in **golden transcript** under [`tests/golden/baseline/`](../tests/golden/baseline/);
+the transcripts are regenerated by `python3 -m tests.golden.capture` and
+diffed in CI, so the cycle counts and directive names below stay
+in sync with the engine's actual behavior.
+
+> Behavior demos (autonomy, commit policy, hard floor, verification)
+> live in [`showcase.md`](showcase.md). This file is the cycle-trace
+> companion: input → directives → outcome.
+
+---
+
+## 1. Backend ticket → ship — `/implement-ticket`
+
+**Anchor:** [`tests/golden/baseline/GT-1/`](../tests/golden/baseline/GT-1/) ·
+[`tickets/gt-1-happy.json`](../tests/golden/sandbox/tickets/gt-1-happy.json)
+
+**Input** — a ticket payload with three concrete acceptance criteria:
+
+```text
+GT-1-MULT — Add multiply(a, b) to the toy calculator
+AC: signature multiply(a: int, b: int) -> int returning the product;
+    edge cases multiply(0, n)=0, multiply(-2, 3)=-6;
+    pytest test_multiply_returns_product in tests/test_calculator.py.
+```
+
+**Trace** — five cycles, exit code `0` on the last:
+
+| Cycle | Directive | What the agent does |
+|---|---|---|
+| c1 | `create-plan` | Builds the three-step plan (impl, test, run) |
+| c2 | `apply-plan` | Edits `src/calculator.py` and `tests/test_calculator.py` |
+| c3 | `run-tests` | `pytest` — `4 passed` (targeted scope) |
+| c4 | `review-changes` | Four judges (bug, security, test-coverage, code-quality) — `success` |
+| c5 | _(none)_ | Engine emits the delivery report, exits `0` |
+
+**Outcome** — verified delivery report at
+[`GT-1/delivery-report.md`](../tests/golden/baseline/GT-1/delivery-report.md):
+plan, changes, test verdict, judge findings, suggested next command
+(`/commit`).
+
+**Anchored in:** [`commands/implement-ticket.md`](../.agent-src/commands/implement-ticket.md)
+(eight-step contract) · [`work_engine/dispatcher.py`](../.agent-src/templates/scripts/work_engine/dispatcher.py)
+(`STEP_ORDER`).
+
+---
+
+## 2. Free-form prompt → ship — `/work`
+
+**Anchor:** [`tests/golden/baseline/GT-P1/`](../tests/golden/baseline/GT-P1/) ·
+[`prompts/gt-p1-high.txt`](../tests/golden/sandbox/prompts/gt-p1-high.txt)
+
+**Input** — one line, no AC, no ticket:
+
+```text
+Add modulo(a, b) to src/calculator.py — return a % b for ints
+```
+
+**Trace** — six cycles. The extra cycle vs. GT-1 is the
+`refine-prompt` step that reconstructs the prompt into AC + assumptions
++ confidence band before any plan runs:
+
+| Cycle | Directive | Effect |
+|---|---|---|
+| c1 | `refine-prompt` | High confidence — AC reconstructed, no halt |
+| c2 | `create-plan` | Two-step plan |
+| c3 | `apply-plan` | Edits `src/calculator.py` |
+| c4 | `run-tests` | targeted pass |
+| c5 | `review-changes` | judges green |
+| c6 | _(none)_ | delivery report, exit `0` |
+
+**Outcome** — `success`. The same dispatcher and judges as GT-1; only
+the input envelope (`input.kind="prompt"` vs `"ticket"`) differs.
+
+**Anchored in:** [`commands/work.md`](../.agent-src/commands/work.md) ·
+[`skills/refine-prompt/SKILL.md`](../.agent-src/skills/refine-prompt/SKILL.md)
+· [`docs/contracts/adr-prompt-driven-execution.md`](contracts/adr-prompt-driven-execution.md).
+
+---
+
+## 3. UI improvement → review-loop ship — `/work` (UI track)
+
+**Anchor:** [`tests/golden/baseline/GT-U2/`](../tests/golden/baseline/GT-U2/) ·
+[`diffs/gt-u2-improve-diff.diff`](../tests/golden/sandbox/diffs/gt-u2-improve-diff.diff)
+
+**Input** — a Blade diff that adds a `<label>` and a heading change to
+`resources/views/contact.blade.php`. The input shape (a diff, not a
+prompt) routes the engine onto the **UI track** instead of the
+generic implement loop.
+
+**Trace** — six cycles, none of them `create-plan` / `apply-plan` /
+`run-tests`. The UI track has its own directive set:
+
+| Cycle | Directive | Effect |
+|---|---|---|
+| c1 | `existing-ui-audit` | Inventory existing components / tokens before any new design |
+| c2 | `ui-design-brief` | Brief for the proposed change |
+| c3 | _(none — `_no_directive`)_ | Engine threads forward to the apply step |
+| c4 | `ui-apply-plain` | Apply the diff |
+| c5 | `ui-design-review-plain` | Design review judge |
+| c6 | _(none)_ | delivery report, exit `0` |
+
+**Outcome** — `success`. The audit-first ordering is enforced by the
+[`ui-audit-gate`](../.agent-src/rules/ui-audit-gate.md) rule: any
+non-trivial UI change without `state.ui_audit` halts before design.
+
+**Anchored in:** [`docs/ui-track-mental-model.md`](ui-track-mental-model.md) ·
+[`rules/ui-audit-gate.md`](../.agent-src/rules/ui-audit-gate.md) ·
+[`skills/existing-ui-audit/SKILL.md`](../.agent-src/skills/existing-ui-audit/SKILL.md).
+
+---
+
+## 4. Blocked on ambiguity — `/implement-ticket` halts
+
+**Anchor:** [`tests/golden/baseline/GT-2/`](../tests/golden/baseline/GT-2/) ·
+[`tickets/gt-2-ambiguity.json`](../tests/golden/sandbox/tickets/gt-2-ambiguity.json)
+
+**Input** — a ticket whose AC list contains a vague entry:
+
+```text
+GT-2-DIV — divide(a, b)
+AC: ... vague acceptance criteria at position(s) 2 ...
+```
+
+**Trace** — one cycle, exit code `1`:
+
+| Cycle | Directive | Effect |
+|---|---|---|
+| c1 | _(none)_ | Engine refuses to plan; surfaces refine prompt |
+
+**Halt surface** — the engine does not write a plan, does not edit any
+file, and emits a numbered-options block (verbatim from
+[`GT-2/halt-markers.json`](../tests/golden/baseline/GT-2/halt-markers.json)):
+
+```text
+> Ticket GT-2-DIV is missing: vague acceptance criteria at position(s) 2.
+> 1. Run `/refine-ticket GT-2-DIV` and re-invoke `/implement-ticket`
+> 2. Provide the missing details in chat — I'll merge them into the ticket
+> 3. Abandon this ticket — too vague to implement
+```
+
+**Outcome** — `halt_unhandled`; the run is recorded as **blocked** in
+the outcome-aware telemetry (`outcomes: ["blocked"]`, see
+[P2 #9](../agents/roadmaps/road-to-1-15-followups.md#phase-9--outcome-aware-telemetry-p2-9)).
+No work is committed, no auto-guess is taken.
+
+**Anchored in:** [`rules/ask-when-uncertain.md`](../.agent-src/rules/ask-when-uncertain.md)
+· [`rules/non-destructive-by-default.md`](../.agent-src/rules/non-destructive-by-default.md)
+· [`skills/refine-ticket/SKILL.md`](../.agent-src/skills/refine-ticket/SKILL.md).
+
+---
+
+## Reproducing these locally
+
+```bash
+python3 -m tests.golden.capture --scenarios GT-1 GT-P1 GT-U2 GT-2
+```
+
+Each scenario writes a fresh `transcript.json`, `delivery-report.md`,
+and `halt-markers.json` under `tests/golden/baseline/<id>/`. CI diffs
+the regenerated output against the committed baseline; drift fails the
+build via the `roadmap-progress-check` and `golden-replay` tasks.

package/docs/getting-started.md

@@ -1,23 +1,39 @@
 # Getting Started
 
+`agent-config` is a stack-agnostic orchestration contract for coding
+agents. The installer detects the project shape (Composer / npm / both /
+neither) and wires the matching glue. **Pick the entrypoint that
+matches the project**, not the language you happen to prefer.
+
 ## Installation
 
+The installer is the same orchestrator across stacks — it reads
+`composer.json` and/or `package.json`, syncs the payload, and generates
+the tool-specific glue. Pick one entrypoint:
+
 ```bash
-# Composer (PHP) — two steps: install, then run the orchestrator
+# Composer-based projects (PHP / Laravel / Symfony / Zend / Laminas)
 composer require --dev event4u/agent-config
 php vendor/bin/install.php
 # Equivalent: bash vendor/event4u/agent-config/scripts/install
 
-# npm (JavaScript/TypeScript) — the orchestrator runs via postinstall
+# npm-based projects (Next.js / React / Node / Vue / plain JS/TS)
 npm install --save-dev @event4u/agent-config
-# Re-run or pick a profile:
+# Postinstall runs the orchestrator. Re-run or pick a profile:
 # bash node_modules/@event4u/agent-config/scripts/install --profile=balanced
+
+# Mixed Composer + npm projects (Laravel + Inertia, Symfony + Vue, …)
+# Run both — the orchestrator merges results, no double-write.
+
+# Stack-less or polyglot repos (no Composer, no npm)
+git clone https://github.com/event4u-app/agent-config /tmp/agent-config
+bash /tmp/agent-config/scripts/install --target "$PWD"
 ```
 
 That's it. Your agent now follows your team's standards. The orchestrator
 runs a bash payload sync and a Python bridge generator (Python 3 is
 recommended; without it the payload sync still runs). No Task or Make
-required for end users.
+required for end users — those are contributor-only.
 
 ## Project CLI — `./agent-config`
 
@@ -99,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 55 rules. No configuration needed.
+This is enforced automatically by 57 rules. No configuration needed.
 
 ---
 
@@ -131,13 +147,15 @@ Your agent now understands slash commands:
 |---|---|
 | `/commit` | Stage and commit with Conventional Commits |
 | `/create-pr` | Create PR with Jira-linked description |
-| `/fix-ci` | Fetch and fix GitHub Actions failures |
+| `/fix ci` | Fetch and fix GitHub Actions failures |
+| `/optimize skills` | Audit skills, find duplicates, run linter |
+| `/feature plan` | Interactively plan a feature |
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log |
 | `/chat-history-resume` | Recover context after a crashed or switched session |
 | `/chat-history-clear` | Wipe the chat-history log (with confirmation) |
 
-→ [Browse all 77 commands](../.agent-src/commands/)
+→ [Browse all 69 active commands](../.agent-src/commands/)
 
 ---
 
@@ -173,7 +191,7 @@ See the [`chat-history` rule](../.agent-src/rules/chat-history-ownership.md) and
 ## Next steps
 
 1. **Stay on `minimal`** — use it for a few days, see if the difference is noticeable
-2. **Try commands** — `/commit`, `/create-pr`, `/fix-ci` are great starting points
+2. **Try commands** — `/commit`, `/create-pr`, `/fix ci` are great starting points
 3. **Upgrade when ready** — switch to `balanced` to let the runtime dispatcher execute skills that declare a shell command
 4. **Customize** — add [project overrides](customization.md) for your team's specific patterns