@event4u/agent-config 1.15.0 → 1.17.0

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

@@ -4,8 +4,7 @@ stability: beta
 
 # UI Track — Flow Contract
 
-> Technical contracts for the UI directive sets shipped under
-> [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md).
+> Technical contracts for the UI directive sets.
 > Sibling of [`implement-ticket-flow.md`](implement-ticket-flow.md) — that
 > doc covers `backend`; this one covers `ui`, `ui-trivial`, and the
 > `mixed` set that stitches both.
@@ -14,11 +13,10 @@ stability: beta
 > - **Status:** Phase 1–6 shipped — audit / design / apply / review /
 >   polish handlers live under
 >   [`.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/).
->   Mixed (Phase 4) under `directives/mixed/`. `ui-trivial` (Phase 2 Step 6)
->   under `directives/ui_trivial/`. R4 (Visual Review Loop) added the
+>   Mixed under `directives/mixed/`. `ui-trivial` under
+>   `directives/ui_trivial/`. R4 (Visual Review Loop) added the
 >   a11y gate, the preview envelope, and a polish-termination rewrite
->   that splits subjective ceilings from objective a11y blocks — see
->   [`road-to-visual-review-loop.md`](../../agents/roadmaps/road-to-visual-review-loop.md).
+>   that splits subjective ceilings from objective a11y blocks.
 >   Golden Transcripts GT-U1..U4, U7, U8, U9..U12 plus GT-U5 (mixed
 >   flow), GT-U6A/B (stack dispatch), and R4's GT-U13..U15 (a11y polish,
 >   a11y ceiling, preview render failure) pin happy-path, ambiguity,
@@ -42,8 +40,6 @@ sentinels that release each gate.
   `SKILL.md` files.
 - A migration guide for the schema — see
   [`implement-ticket-flow.md`](implement-ticket-flow.md#state-schema-v1).
-- A roadmap — phased delivery lives in
-  [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md).
 
 ## The four directive sets
 
@@ -323,16 +319,10 @@ suite asserts every `BLOCKED` path has a matching declaration.
 - [`implement-ticket-flow.md`](implement-ticket-flow.md) — sibling
   contract for the `backend` set; covers `DeliveryState`, schema v1,
   hooks, persona policies, replay protocol.
-- [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md)
-  — phased delivery and Golden-Transcript matrix.
-- [`road-to-product-ui-track-followup.md`](../../agents/roadmaps/archive/road-to-product-ui-track-followup.md)
-  — pinned GT-U5 (mixed flow), GT-U6A/B (stack dispatch), GT-U7
-  (trivial happy path), GT-U8 (trivial reclassification).
-- [`road-to-visual-review-loop.md`](../../agents/roadmaps/road-to-visual-review-loop.md)
-  — R4 contract: a11y gate, preview envelope, polish-termination
-  rewrite. Pinned by GT-U13 (a11y polish), GT-U14 (a11y ceiling),
-  GT-U15 (preview render failure).
+- [`adr-product-ui-track.md`](adr-product-ui-track.md) — locked
+  decisions for the UI track (R3) and the visual-review-loop
+  amendment (R4: a11y gate, preview envelope, polish-termination).
 - [`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,22 @@ 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). |
+
+> **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
+
+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 58 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 95 active commands](../.agent-src/commands/)
 
 ---
 
@@ -149,8 +167,9 @@ for every profile), the agent keeps a JSONL log of your conversation in
 rotates at the size configured in the profile (`128 KB` on `minimal`,
 `256 KB` on `balanced`, `512 KB` on `full`).
 
-When a chat opens and finds an existing log, the agent runs a
-4-state ownership check and chooses the right flow:
+When a chat opens and finds an existing log, the host agent is
+instructed to run a 4-state ownership check and choose the right
+flow:
 
 - **match** — this chat already owns the file. Append silently.
 - **foreign** — a different session's file. You get 3 options:
@@ -173,7 +192,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
 

package/docs/github-topics.md

@@ -13,8 +13,12 @@ ai-coding
 agent-skills
 agent-rules
 governance
+orchestration
 laravel
 php
+nextjs
+nodejs
+typescript
 devcontainer
 augment-agent
 claude-code
@@ -30,8 +34,9 @@ agentskills-standard
 | `agent-skills` | Aligns with the [Agent Skills](https://agentskills.io) community spec |
 | `agent-rules` | Complementary — rules govern behavior, skills provide expertise |
 | `governance` | Differentiates from prompt collections |
-| `laravel` | Primary domain — Laravel projects are the main audience |
-| `php` | Broader PHP audience |
+| `orchestration` | Captures the core identity — a deterministic orchestration contract / state machine |
+| `laravel`, `php` | Reference-implementation stack — currently the deepest skill density |
+| `nextjs`, `nodejs`, `typescript` | Parallel skill sets for JS/TS surfaces (project-analysis, UI directives) |
 | `devcontainer` | One of our 4 core concerns |
 | `augment-agent`, `claude-code`, `copilot` | Tool-specific discovery |
 | `agentskills-standard` | SKILL.md format is compatible with the agentskills.io spec |
@@ -53,8 +58,12 @@ gh repo edit event4u-app/agent-config \
   --add-topic agent-skills \
   --add-topic agent-rules \
   --add-topic governance \
+  --add-topic orchestration \
   --add-topic laravel \
   --add-topic php \
+  --add-topic nextjs \
+  --add-topic nodejs \
+  --add-topic typescript \
   --add-topic devcontainer \
   --add-topic augment-agent \
   --add-topic claude-code \
@@ -69,7 +78,7 @@ curl -X PUT \
   -H "Authorization: Bearer $GITHUB_TOKEN" \
   -H "Accept: application/vnd.github+json" \
   https://api.github.com/repos/event4u-app/agent-config/topics \
-  -d '{"names":["ai-coding","agent-skills","agent-rules","governance","laravel","php","devcontainer","augment-agent","claude-code","copilot","agentskills-standard"]}'
+  -d '{"names":["ai-coding","agent-skills","agent-rules","governance","orchestration","laravel","php","nextjs","nodejs","typescript","devcontainer","augment-agent","claude-code","copilot","agentskills-standard"]}'
 ```
 
 ## Verify