@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/contexts/communication/rules-auto/think-before-action-mechanics.md

@@ -0,0 +1,98 @@
+# Think Before Action — mechanics
+
+Workflow tables, verification matrix, and failure modes for the
+[`think-before-action`](../../../rules/think-before-action.md) rule.
+The rule body holds the obligation surface (analyze before coding,
+verify with real tools, no blind retries). This file is the lookup
+material agents pull when the rule fires.
+
+## The Developer Workflow — five-step order
+
+Work like a developer, not a text generator. Skipping steps 1–3 is the
+#1 cause of wrong implementations and wasted retries.
+
+1. **Understand** — Read the task, ticket, acceptance criteria. Unclear
+   → ask, don't assume.
+2. **Analyze** — Read affected code, trace data flow, compare with
+   requirements and existing patterns.
+3. **Plan** — Decide what to change, what NOT to change, and how to
+   verify success.
+4. **Implement** — Focused changes. Follow existing patterns. No
+   unrelated rewrites.
+5. **Verify** — Run tests, hit the endpoint, check the UI. Real
+   execution, never "should work".
+
+## Minimum read set — read before you write
+
+Before editing code, read the minimum set that defines its behavior:
+
+1. **Symbol under edit** — full method/function body, not just the
+   planned line.
+2. **Direct callers** — one level up (`grep -rn "<symbol>"` + open
+   the matches).
+3. **Tests** — if a test file exists, it encodes the contract.
+4. **One layer of related abstractions** — interface, parent class,
+   or trait (one hop, not the full hierarchy).
+5. **Data changes** — the migration that created the column + any
+   seeder/factory that references it.
+
+Stop expanding once you can explain, in your own words, what the
+symbol does, who calls it, and what breaks if you change its
+behavior. Cannot → read more.
+
+## Consult memory before editing
+
+Invariants live in the memory layer; architectural rationale lives in ADRs.
+Via [`memory-access`](../../../../../docs/guidelines/agent-infra/memory-access.md),
+call `retrieve(types=["domain-invariants"], keys=<touched paths>, limit=3)` —
+a matching `domain-invariant` is a hard constraint. For *why* the current
+shape exists, check the ADR index `docs/decisions/INDEX.md`. Cite the `id` /
+ADR number if a match influences the plan.
+
+## Verify with real tools
+
+| What changed | How to verify |
+|---|---|
+| **Backend/API** | `curl`, Postman (or Postman MCP if available), test endpoint |
+| **Frontend/UI** | Playwright MCP or browser — check rendered state, interactions |
+| **Logic/flow** | Xdebug (or Xdebug MCP if available) — trace execution, inspect variables |
+| **CLI/Jobs** | Run the command, check side effects, verify exit code |
+| **Database** | Query the result, check migrations ran correctly |
+
+If a debugging/testing tool is available as MCP server — prefer it
+over manual alternatives. Verification not possible (no endpoint, no
+UI, no test) → state what is missing and explain how the change
+should be tested.
+
+## Reduce output — targeted tools over full dumps
+
+Never load full datasets into context. Extract what you need:
+
+- `jq` for JSON: `curl -s /api/users | jq '.[0] | {id, email}'` — not the full response
+- `rg` / `grep` for text: search specific patterns, not full files
+- `head`, `tail`, `cut`, `sort`, `uniq` for narrowing results
+- `--filter`, `--json`, `--format` flags on CLI tools — use them
+- Laravel: `route:list --json | jq` over raw `route:list` dump
+- Logs: filter by request ID, timestamp, or error type — not full log files
+
+## No blind retries
+
+- Failure → **read the error**, analyze the cause, then fix it.
+- Do NOT retry the same approach hoping for a different result.
+- Do NOT loop through trial-and-error when one targeted inspection
+  would reveal the cause.
+- Max 2 retries for the same approach — then stop and rethink.
+
+## Open files are context, not intent
+
+The editor may report that the user has a file open. Background
+context only — does NOT mean the user's message is about that file.
+
+- The user's message determines intent — not which file is open.
+- A user can have `README.md` open and type `/condense` — intent is
+  to condense, not to discuss the README.
+- A user can have `UserController.php` open and ask "how do tests
+  work?" — intent is testing, not the controller.
+- Treat the open file as relevant only when the user's message
+  explicitly references it (e.g. "fix this file", "what does this
+  do?", "update the open file").

package/dist/agent-src/contexts/contracts/artifact-engagement-flow.md

@@ -0,0 +1,259 @@
+---
+stability: beta
+---
+
+# Artifact Engagement — Flow & Recording Contract
+
+> Cross-cutting reference for the artifact-engagement telemetry system.
+> The schema, CLI, and engine ship first; the agent-side hooks (this
+> document) ship after.
+>
+> - **Created:** 2026-04-30
+> - **Status:** schema, engine, recording, aggregator, renderer, and
+>   redaction validator are in place. Dogfooding next.
+
+This document is the stable reference for **what gets recorded, when, and
+under which constraints**. The roadmap tracks phased delivery; the rule
+([`artifact-engagement-recording`](../../.agent-src.uncondensed/rules/artifact-engagement-recording.md))
+tells the agent when to fire; this doc explains the contract every
+recording must honour.
+
+## What this is
+
+A measurement layer that tells maintainers which **skills, rules,
+commands, guidelines and personas** the agent actually consults and
+applies during a `/implement-ticket` or `/work` run. The output (a local
+JSONL log) becomes the input to the Phase 4 aggregator + report renderer.
+
+## What this is *not*
+
+- Token-spend tracking — handled separately by the cost-profile system.
+- Tool-call telemetry — out of scope.
+- A retirement decision-maker — Phase 4's report surfaces signal; humans
+  decide what to retire.
+- A consumer-facing analytics product — local-only, opt-in, never
+  uploaded.
+
+## Threat model in one paragraph
+
+Engagement data is **observation**, not delivery. A missed event is
+cheap. A leaked prompt, a leaked path, or a leaked secret is not. Every
+field in the schema is **id-only**: no free-text, no payloads, no paths.
+The CLI rejects oversized strings on the input boundary; the agent must
+not even attempt to write content.
+
+## When the agent records
+
+Two granularities, one per task or one per phase-step:
+
+```
+refine → memory → analyze → plan → implement → test → verify → report
+                          ↑
+            granularity: phase-step → 1 record per arrow crossed
+            granularity: task        → 1 record on terminal state only
+```
+
+The setting lives at `telemetry.artifact_engagement.granularity` in
+`.agent-settings.yml`. Default `task`. Both flows
+([`/implement-ticket`](../../.agent-src.uncondensed/commands/implement-ticket.md)
+and [`/work`](../../.agent-src.uncondensed/commands/work.md)) use the
+same eight-step contract from
+[`implement-ticket-flow.md`](implement-ticket-flow.md).
+
+### Boundary semantics
+
+A boundary is **closed** when:
+
+- The dispatcher returns `SUCCESS`, `BLOCKED`, or `PARTIAL` for the
+  current step (phase-step granularity), or
+- The full eight-step flow reaches a terminal state (task granularity).
+
+A boundary is **never** closed by:
+
+- An error inside the agent's tool call (the user's task is paramount;
+  see "failure modes" below).
+- A model-side exception or timeout.
+- Settings reload mid-flow — settings are read once per task and cached.
+
+Within a single boundary, repeated `consulted` / `applied` mentions of
+the same `<kind>:<id>` pair **dedupe**. Reading `php-coder` three times
+records once.
+
+## What counts as consulted vs applied
+
+| Term | Meaning | Examples |
+|---|---|---|
+| **`consulted`** | The agent **read** the artefact this boundary | Opened `SKILL.md`, scanned a rule body, looked at a guideline, checked persona contract, cited the artefact id in reasoning |
+| **`applied`** | The artefact **influenced the output** this boundary | A skill's procedure produced the code; a rule's gate halted a flow; a guideline's pattern shaped the diff |
+
+`applied` is a strict subset of `consulted`. When in doubt → record as
+`consulted` only. Over-recording `applied` inflates the engagement
+signal and defeats the whole point of the system.
+
+## Forbidden — what NEVER goes into a record
+
+The privacy contract is enforced at **four** layers — schema (write
+gate), aggregator (read gate via `parse_event`), renderer (export gate),
+and CLI (surface gate). Each layer rejects the same set of shapes;
+defense in depth means a leak has to bypass all four to escape:
+
+- File paths — any string containing `/`, `\`, or a control character.
+- File extensions — trailing `.md`, `.py`, `.json`, `.yaml`, `.yml`,
+  `.php`, `.ts`, `.js`, etc. Detected by
+  `re.compile(r"\.[a-z0-9]{1,10}$", re.IGNORECASE)` in
+  `telemetry.engagement.check_id_redaction`.
+- Source code, prompts, ticket bodies, AC text, comments.
+- Branch names, commit shas, PR numbers, URLs.
+- Secrets, env vars, credentials, customer data.
+- Free-text strings longer than 200 chars.
+- Leading or trailing whitespace, tabs, newlines.
+- Empty strings.
+
+The id namespaces are stable and bounded:
+
+| Kind | Source | Example |
+|---|---|---|
+| `skills` | `dist/agent-src/skills/<id>/SKILL.md` | `php-coder`, `eloquent` |
+| `rules` | `dist/agent-src/rules/<id>.md` | `scope-control`, `language-and-tone` |
+| `commands` | `dist/agent-src/commands/<id>.md` | `commit`, `create-pr` |
+| `guidelines` | `docs/guidelines/<path>/<id>.md` | `agent-interaction-and-decision-quality` |
+| `personas` | `dist/agent-src/personas/<id>.md` | `qa`, `senior-engineer` |
+
+`task_id` is the ticket key (`PROJ-123`) for `/implement-ticket` or a
+short opaque slug derived from the prompt for `/work`. Branch names,
+file paths, and free-text titles are forbidden in `task_id` — see the
+schema's `EngagementSchemaError` cases.
+
+### The four enforcement layers
+
+1. **Schema (write gate)** — `EngagementEvent.validate()` in
+   `telemetry/engagement.py` runs `check_id_redaction` over `task_id`
+   and every `consulted` / `applied` artefact id. The CLI exits `1`
+   when this fires; nothing reaches the JSONL.
+2. **Aggregator (read gate)** — `aggregator._iter_events` calls
+   `parse_event`, which re-runs the same validator. A pre-validator
+   line (e.g. an archived snapshot from before the validator landed)
+   is **skipped** and counted in `result.skipped_lines`. The renderer
+   never sees it.
+3. **Renderer (export gate)** — `_stat_to_dict` (JSON) and the
+   markdown row builder both call `check_id_redaction` again before
+   emitting any id. If a caller bypasses `parse_event` and hand-builds
+   an `AggregateResult`, the renderer raises `EngagementSchemaError`
+   instead of producing the row.
+4. **CLI (surface gate)** — `telemetry_report.main` catches
+   `EngagementSchemaError` from the renderer and exits `2` with a
+   `redaction validator refused report` message. A bad row is never
+   written to stdout, never piped to a teammate.
+
+A leak would have to defeat all four layers — write the JSONL outside
+the CLI, parse it outside `parse_event`, render it outside the
+project's renderer, and ship it to a teammate without the CLI in the
+loop. The contract treats that as out of scope.
+
+## How the agent records
+
+```bash
+./agent-config telemetry:record \
+  --task-id "$TASK_ID" \
+  --boundary task \
+  --consulted skills:php-coder \
+  --consulted rules:scope-control \
+  --applied skills:php-coder
+```
+
+Exit codes (the agent must read these):
+
+| Exit | Meaning | Action |
+|---|---|---|
+| `0` | Recorded, or telemetry disabled (silent no-op) | Continue |
+| `1` | Schema validation failed | Log internally, **continue** the user's task — do not halt |
+| `2` | IO failure (lock contention, disk full) | Same — observation, not delivery |
+
+Schema-rejection messages go to stderr; the agent reads them once and
+moves on. The user's task always takes priority.
+
+## Failure modes — DO NOT block the user's task
+
+- Telemetry is **observation**, not a delivery requirement.
+- A missing event is cheap; a halted task because telemetry can't write
+  is a critical failure mode that defeats the whole opt-in property.
+- The only error the agent surfaces to the user: when the user asked
+  for telemetry (`telemetry:status` confirms enabled) but no event
+  reached the log over a full task — that is a real bug.
+
+## Cost floor — what "default-off" means
+
+When `telemetry.artifact_engagement.enabled: false` (or section absent):
+
+- The rule is `auto` and the description does not match a typical
+  conversation; the rule never loads. Cost floor: 0 tokens.
+- The CLI exits `0` with no output and no file IO.
+- The engine (`work_engine.dispatcher`, `work_engine.cli`) does not
+  import any `telemetry.*` module — locked by
+  [`tests/telemetry/test_cost_floor.py`](../../tests/telemetry/test_cost_floor.py).
+- On cloud surfaces (Claude.ai Web, Skills API), the rule's
+  `cloud_safe: noop` marker keeps the rule inert regardless of settings.
+
+## Where the JSONL lives
+
+Default path: `.agent-engagement.jsonl` in the consumer repo root.
+Configurable via `telemetry.artifact_engagement.output.path`. The path
+is **always** added to the consumer's `.gitignore` block by the
+installer (Phase 1 wiring). Verify locally:
+
+```
+$ grep agent-engagement .gitignore
+.agent-engagement.jsonl
+```
+
+## How to audit a JSONL by hand
+
+The fastest path is the project's own validator — it enforces every
+rule listed above:
+
+```bash
+# Validate every line against the schema + redaction floor
+python3 -c '
+import pathlib, sys
+sys.path.insert(0, ".agent-src.uncondensed/templates/scripts")
+from telemetry.engagement import EngagementSchemaError, parse_event
+log = pathlib.Path(".agent-engagement.jsonl")
+ok = bad = 0
+for i, line in enumerate(log.read_text().splitlines(), 1):
+    if not line.strip():
+        continue
+    try:
+        parse_event(line + "\n")
+        ok += 1
+    except EngagementSchemaError as e:
+        bad += 1
+        print(f"line {i}: {e}", file=sys.stderr)
+print(f"{ok} valid, {bad} rejected")
+'
+
+# A bad-line spot-check that does not depend on the validator
+python3 -c '
+import json, pathlib, re
+forbidden = re.compile(r"[/\\\\]|\.[a-z0-9]{1,10}$", re.IGNORECASE)
+for line in pathlib.Path(".agent-engagement.jsonl").read_text().splitlines():
+    if not line.strip():
+        continue
+    obj = json.loads(line)
+    for kind in ("consulted", "applied"):
+        for ids in obj.get(kind, {}).values():
+            for v in ids:
+                if forbidden.search(v) or len(v) > 200:
+                    print("LEAK:", v)
+'
+```
+
+Either recipe is safe to run on a co-worker's archived JSONL — neither
+writes anything, both surface the same shapes the four enforcement
+layers reject.
+
+## See also
+
+- [`artifact-engagement-recording`](../../.agent-src.uncondensed/rules/artifact-engagement-recording.md) — agent-side trigger
+- [`implement-ticket-flow`](implement-ticket-flow.md) — the eight-step contract this rule observes
+- [`scripts/telemetry/`](../../.agent-src.uncondensed/templates/scripts/telemetry/) — schema, boundary session, settings reader
+- [`tests/telemetry/`](../../tests/telemetry/) — contract enforcement (schema, settings, aggregator, renderer, CLI, cost-floor, redaction)

package/dist/agent-src/contexts/contracts/consumer-agents-md-guide.md

@@ -0,0 +1,127 @@
+# Consumer `AGENTS.md` — fill-out guide
+
+> Outboard target for the placeholder sections that used to live verbatim
+> in the consumer-template `AGENTS.md`. The template is now Thin-Root; this
+> guide carries the prose / examples / `<!-- … -->` hints that the
+> consumer copies in only when they need them.
+
+After installing `event4u/agent-config`, the consumer project gets:
+
+- `AGENTS.md` at project root — Thin-Root, points here.
+- `.augment/`, `dist/agent-src/`, `.claude/`, `.cursor/`, `.clinerules/`,
+  `.windsurfrules` — installed artifacts, never hand-edited.
+- `agents/` — project docs / roadmaps / sessions / overrides.
+- `.agent-settings.yml` — project config consumed by skills.
+
+## Recommended `AGENTS.md` shape
+
+The installed Thin-Root carries: project name + description, layer table,
+five-question emergency triage block, pointers to this guide. Copy any of
+the sections below into AGENTS.md only when the project actually needs
+the content there (e.g. an unusual stack note that no `agents/` doc
+covers). Default: leave AGENTS.md thin and put detail under `agents/`.
+
+## Tech-stack section (optional copy-in)
+
+```markdown
+## Tech Stack
+
+- **Language:** {{primary_language}}
+- **Framework:** {{framework}}        # Laravel 11 / Next.js 15 / Rails 7 / Django 5
+- **Database:** {{database}}          # PostgreSQL / MySQL / MariaDB / SQLite
+- **Testing:** {{test_framework}}     # Pest / PHPUnit / Jest / Vitest / pytest
+- **Code style:** {{code_style_tool}} # ECS / PHPStan / Ruff / ESLint
+```
+
+## Development-setup section (optional copy-in)
+
+```markdown
+## Development Setup
+
+```bash
+{{dev_start_command}}    # make start / docker compose up / npm run dev / php artisan serve
+{{dev_test_command}}     # make test / docker compose exec app bash / npm test / php artisan test
+```
+
+### Environment files
+
+| File | Purpose |
+|---|---|
+| `.env` | Main environment |
+| `.env.local` | Local overrides |
+| `.env.testing` | Testing environment |
+```
+
+## Project-structure section (optional copy-in)
+
+```markdown
+## Project Structure
+
+{{project_structure_notes}}   # Where new features go, module/component
+                              # boundaries, namespace conventions.
+```
+
+## Testing section (optional copy-in)
+
+```markdown
+## Testing
+
+{{testing_notes}}             # Framework quirks, how to run all/targeted
+                              # tests, test data strategy (seeders /
+                              # factories / fixtures), performance-critical
+                              # suites.
+```
+
+## Quality-tools section (optional copy-in)
+
+```markdown
+## Quality Tools
+
+{{quality_tools_notes}}       # Which linters/formatters run, whether
+                              # they auto-fix or report only, CI
+                              # enforcement level.
+```
+
+## Recommended entry flow
+
+Two entrypoints share the same engine and Option-A loop; pick by input shape:
+
+| You have | Command | Envelope |
+|---|---|---|
+| Ticket id, URL, or pasted ticket payload | [`/implement-ticket`](.augment/commands/implement-ticket.md) | `input.kind="ticket"` |
+| Free-form goal, no ticket | [`/work`](.augment/commands/work.md) | `input.kind="prompt"` |
+
+Both drive the linear flow `refine → memory → analyze → plan → implement
+→ test → verify → report` with block-on-ambiguity semantics and no
+auto-git.
+
+`/work` adds a confidence-band gate at `refine`: the
+[`refine-prompt`](.augment/skills/refine-prompt/SKILL.md) skill scores
+the prompt on five dimensions and the engine proceeds **silently** on
+`high`, halts with an **assumptions report** on `medium`, or halts with
+**one clarifying question** on `low` (per the `ask-when-uncertain` Iron
+Law). UI-shaped prompts route through the product UI track (`directive_set`
+`ui` / `ui-trivial` / `mixed`) — `audit → design → apply → review →
+polish` with a hard audit gate before any `apply`.
+
+Persona comes from `.agent-settings.yml` (`roles.active_role`). Use
+`/commit` and `/create-pr` explicitly after the delivery report. The
+two flows are mutually exclusive at the state-file level: one
+`.work-state.json` carries one envelope at a time; the engine refuses to
+switch mid-flight.
+
+## Multi-agent support
+
+| Tool | Rules | Skills | How |
+|---|---|---|---|
+| **Augment Code** | `.augment/rules/` | `.augment/skills/` | Native (source) |
+| **Claude Code** | `.claude/rules/` | `.claude/skills/` | Symlinks + Agent Skills standard |
+| **Cursor** | `.cursor/rules/` | — | Symlinks |
+| **Cline** | `.clinerules/` | — | Symlinks |
+| **Windsurf** | `.windsurfrules` | — | Concatenated file |
+| **Gemini CLI** | `GEMINI.md` | — | Symlink → AGENTS.md |
+
+Reinstall agent-config: `composer update event4u/agent-config` (PHP) or
+`npm update @event4u/agent-config` (JS). Don't run package-internal
+`task` commands from a consumer project; they only work in the
+agent-config repo itself.

package/dist/agent-src/contexts/contracts/emergency-triage-block.md

@@ -0,0 +1,53 @@
+# Emergency Triage Block — canonical source
+
+> Canonical content of the **Emergency Triage** block referenced by the
+> `agents-md-thin-root` skill. Both the package-root `AGENTS.md` and
+> `.agent-src.uncondensed/templates/AGENTS.md` (consumer template)
+> embed this block verbatim. Drift is caught by the `lint-agents-md`
+> task in the package's CI pipeline.
+
+The block exists so a host agent can answer five basic questions from
+the root file alone when network access, context-engine retrieval, or
+linked-file fetches are degraded. Each answer fits on one line.
+
+## Package-root variant
+
+Use this variant in `AGENTS.md` at the package root.
+
+```
+## Emergency triage — read this when nothing else is reachable
+
+1. **What is this repo?** — `event4u/agent-config`, a governed skill / rule / command suite for AI coding tools (no application runtime).
+2. **What language?** — All `.md` content is English; agents mirror the user's language at runtime.
+3. **Where do I edit?** — `.agent-src.uncondensed/` only. Never `dist/agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`.
+4. **Lint / test / sync entry point?** — `task ci` (full pipeline). Subsets: `task sync`, `task generate-tools`, `task lint-skills`, `task test`.
+5. **Where do the always-active rules live?** — `dist/agent-src/rules/` (kernel = 9 Iron-Law rules; tier-1 / tier-2 routed via `dist/agent-src/router.json`).
+```
+
+## Consumer-template variant
+
+Use this variant in `.agent-src.uncondensed/templates/AGENTS.md`. The
+consumer's `AGENTS.md` lands at the consumer-project root after install.
+
+```
+## Emergency triage — read this when nothing else is reachable
+
+1. **What is this repo?** — Consumer project; agent-config is installed as a shared skill / rule / command suite at `.augment/` and `dist/agent-src/`.
+2. **What language?** — Project-specific; agents mirror the user's language at runtime.
+3. **Where do I edit agent-config?** — Do not edit `.augment/` or `dist/agent-src/` here; they are installed artifacts. Project edits live in `agents/` and project source.
+4. **Lint / test / sync entry point?** — Project-specific (see project README); agent-config itself reinstalls via `composer update event4u/agent-config` or `npm update @event4u/agent-config`.
+5. **Where do the always-active rules live?** — `dist/agent-src/rules/` (kernel = 9 Iron-Law rules; tier-1 / tier-2 routed via `dist/agent-src/router.json`).
+```
+
+## Why two variants
+
+The package-root and the consumer template answer the same five
+questions but in different repos:
+
+- The package-root variant points at this repo's authoring layer
+  (`.agent-src.uncondensed/`) and the package's CI entry point.
+- The consumer variant tells the agent it is in a **consumer** project
+  where `.augment/` is an installed artifact and editing it is wrong.
+
+The questions stay identical so a host agent can recognise the block
+visually regardless of which repo it landed in.

package/dist/agent-src/contexts/execution/non-interactive-contract.md

@@ -0,0 +1,132 @@
+# Non-Interactive & Auto-Detection Contract
+
+Loaded by every command orchestrator that auto-detects a sub-command
+(`/judge`, `/fix`, `/analytics`, `/tests`, `/override`). Holds the
+single source of truth for: TTY/CI detection, the confidence tiers that
+gate auto-detection, `--yes` / `--json` / explicit-sub semantics, the
+two abort schemas, the `auto_detect` kill-switch, the structured
+pre-routing emission, and the rollback procedure.
+
+> **Why this exists (6.1.0 Step 1, AI-council-converged 2026-06-05,
+> claude-sonnet-4-5 + gpt-4o):** every interactive command MUST work
+> non-interactively — CI has no TTY, so a command that blocks on a
+> prompt is "provably wrong for CI/CD". No orchestrator ships
+> auto-detection without honoring this contract.
+
+**Size budget:** ≤ 6,000 chars.
+
+## 1. Surface detection — is a human reachable?
+
+An orchestrator runs in one of two surfaces:
+
+- **Interactive** — a human can answer a numbered-options question this
+  turn (normal chat session, attended terminal).
+- **Non-interactive (CI / headless / autonomous)** — no human can
+  answer before the run ends: `/work`, `/roadmap:process-*`, a CI job,
+  `--json`, or an explicit `--yes`. Treat the surface as non-interactive
+  when **any** of these hold: `CI=true` / `CI=1` in the environment,
+  `stdin` is not a TTY, `--yes` / `--json` is passed, or the caller is
+  another command/skill (not a human turn).
+
+A command MUST NEVER block waiting for input it cannot receive.
+
+## 2. Confidence tiers — declarative, not numeric
+
+An agent does not compute a numeric score; it evaluates a **declarative
+detection table** the orchestrator carries and labels the match:
+
+| Tier | Meaning | Basis must be |
+|---|---|---|
+| **HIGH** | Deterministic signal uniquely names the sub-command | A file/git/flag fact (`git diff --cached` non-empty, `--prune` passed) |
+| **MEDIUM** | Heuristic signal points to one sub-command | A plausible-but-defeasible fact (`plan.md` exists) |
+| **LOW** | No signal, or ≥ 2 signals conflict | Ambiguous / absent |
+
+Every detection row in an orchestrator names its tier **and** its
+`basis` (the concrete condition that matched).
+
+## 3. Behavior matrix — tier × surface
+
+| Confidence | Interactive | Non-interactive (CI / `--yes`) |
+|---|---|---|
+| **HIGH** | Run silently | Run silently |
+| **MEDIUM** | Confirm: show `basis`, ask Y/n | Run **only if** `--yes` / explicit sub; else abort `ambiguous_routing` |
+| **LOW** | Show the sub-command menu, ask | Abort `ambiguous_routing` (even with `--yes`) |
+
+An explicit sub-command (`/judge solo`) **always** wins — detection is
+skipped entirely. `--yes` means "proceed with MEDIUM decisions without
+asking"; it is **not** "run anything regardless of confidence".
+
+## 4. Destructive sub-commands — never on a safe default
+
+A sub-command that mutates or deletes (`analytics prune`, anything
+behind a confirm gate) MUST NOT be reached by auto-detection or a
+safe-default fallback. It runs only on an **explicit** sub-command, and
+in CI only with an explicit `--yes`. A safe default always resolves to
+the **read-only / least-destructive** sibling (`analytics` → `show`,
+`fix` → detect-only, `judge` → `solo`).
+
+## 5. Two abort schemas
+
+When a non-interactive run cannot proceed, emit **structured JSON** and
+exit non-zero — never hang, never guess:
+
+```json
+{ "status": "missing_sub_command",
+  "orchestrator": "analytics",
+  "available": ["analytics/show", "analytics/prune"],
+  "safe_default": "analytics/show",
+  "suggest": "Re-run with: /analytics show" }
+```
+
+```json
+{ "status": "ambiguous_routing",
+  "orchestrator": "judge",
+  "detected_signals": [
+    {"condition": "plan.md exists", "suggests": "judge/steps"},
+    {"condition": "git diff --cached non-empty", "suggests": "judge/on-diff"}],
+  "confidence": "LOW",
+  "suggest": "Re-run with an explicit sub-command: /judge steps OR /judge on-diff" }
+```
+
+`missing_sub_command` = the caller forgot to name one (UX). 
+`ambiguous_routing` = detection could not reach HIGH/MEDIUM (heuristic).
+
+## 6. Structured pre-routing emission
+
+Before invoking the detected sub-command, the agent MUST emit (so the
+decision is auditable and in-band-validated by this contract, not a
+black box):
+
+```json
+{ "orchestrator": "judge", "detected_sub_command": "judge/on-diff",
+  "confidence": "HIGH", "basis": "git diff --cached non-empty", "params": {} }
+```
+
+## 7. Kill-switch — disable auto-detection without a rollback
+
+Three override layers, narrowest wins:
+
+1. **Per-invocation:** `--no-auto-detect` → fall back to the menu
+   (interactive) or `missing_sub_command` (CI).
+2. **Per-orchestrator:** `auto_detect: false` in the command's
+   front-matter → that orchestrator always shows the menu.
+3. **Global:** `commands.auto_detect: disabled | warn | enabled` in
+   `.agent-settings.yml` (default `enabled`; `warn` = detect but always
+   confirm).
+
+A misbehaving heuristic is disabled by config, not by reverting 6.1.0.
+
+## 8. Rollback procedure (every orchestrator references this)
+
+1. Re-run with the explicit sub-command (`/judge solo`) — detection is
+   skipped.
+2. Disable globally: `commands.auto_detect: disabled` in
+   `.agent-settings.yml`.
+3. Disable one orchestrator: set `auto_detect: false` in its
+   front-matter — the change takes effect on the next projection/sync.
+
+## See also
+
+- [`command-clusters`](../../../docs/contracts/command-clusters.md) — the locked cluster/sub-command set.
+- [`user-interaction`](../../rules/user-interaction.md) — numbered-options + recommendation rules the interactive path obeys.
+- [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) — the Hard Floor destructive sub-commands still answer to.