@event4u/agent-config 5.10.0 → 6.0.0

package/dist/agent-src/contexts/communication/rules-auto/source-of-truth-mechanics.md

@@ -0,0 +1,99 @@
+# Source of Truth — mechanics
+
+Workflow, condensation rules, commands workflow, symlink mapping, and
+quick reference for the
+[`source-of-truth`](../../../rules/source-of-truth.md)
+rule. The Iron Rule and the "never edit a generated projection" obligation
+live in the rule; this file is the lookup material the rule pulls
+when authoring or pre-review verification fires.
+
+## Workflow
+
+1. **Create or edit** the file in `src/{path}` (e.g. `src/rules/`, `src/skills/`,
+   `src/agent-src/`, `src/domains/<pack>/`)
+2. **Do NOT auto-condense.** Continue working.
+3. **Before commit/push:** Check if condensation is needed
+   (`bash src/scripts/condense.sh --changed`). If files need condensation,
+   ask the user:
+   ```
+   > 📦 {N} dist/agent-src files need condensation before commit.
+   >
+   > 1. Condense now — run /condense
+   > 2. Later — commit without condensation
+   ```
+4. If condensing: run `/condense` command, then
+   `bash src/scripts/condense.sh --mark-done {path}`
+
+For new non-.md files (`.php`, configs):
+`bash src/scripts/condense.sh --sync` copies them automatically.
+
+**Key change:** Condensation happens once before commit/push — not after every edit.
+This avoids interruptions when work is still in progress.
+
+## What "condense" means
+
+- Remove articles (a, an, the), filler, hedging, connective fluff
+- Shorten phrases: "in order to" → "to", "make sure to" → "ensure"
+- Fragments OK: "Run tests before commit" not "You should always run tests before committing"
+- Merge redundant bullets
+
+## What NEVER changes during condensation
+
+- Code blocks, inline code, URLs, file paths, commands
+- Headings (exact text preserved)
+- Tables (structure preserved, condense cell text only)
+- YAML frontmatter
+- Technical terms, library names, API names
+- Strong language: "NEVER", "MUST", "Do NOT" — these are load-bearing
+
+## Commands workflow
+
+Commands live in `src/agent-src/commands/{name}.md` (single source of truth).
+Claude Code reads them via symlinks in `.claude/skills/{name}/SKILL.md`.
+
+**Required frontmatter for commands:**
+
+```yaml
+name: {command-name}
+description: {what it does}
+disable-model-invocation: true
+```
+
+- `name` and `disable-model-invocation: true` are required for Claude Code compatibility
+- Tools that don't recognise a frontmatter field ignore it — no conflict
+- Template: `src/agent-src/templates/command.md`
+
+**Creating a new command:**
+
+1. Create `src/agent-src/commands/{name}.md` (use template)
+2. Run `python3 src/scripts/skill_linter.py` — must be 0 FAIL
+3. Condense via `/condense`, which writes to `dist/agent-src/commands/`
+4. Run `python3 src/scripts/condense.py --generate-tools` — creates Claude symlink automatically
+
+**Never** create `.claude/skills/{name}/SKILL.md` manually for commands — always use the symlink workflow.
+
+## Multi-agent symlink mapping
+
+`.claude/skills/` contains symlinks to **both** `dist/agent-src/skills/` and `dist/agent-src/commands/`.
+Claude Code treats both as "skills" — but they are different artifact types in our taxonomy.
+
+| `.claude/skills/{name}/SKILL.md` points to... | Actual type |
+|---|---|
+| `dist/agent-src/skills/{name}/SKILL.md` | **Skill** (workflow) |
+| `dist/agent-src/commands/{name}.md` | **Command** (slash-invoked procedure) |
+
+Always check the symlink target to determine the actual artifact type.
+Commands have `disable-model-invocation: true` in their frontmatter.
+
+## Quick reference
+
+| Task | What to do |
+|---|---|
+| Edit existing file | Edit in `src/`, condense to `dist/agent-src/` |
+| Create new `.md` | Create in `src/`, condense to `dist/agent-src/` |
+| Create new non-`.md` | Create in `src/`, run `bash src/scripts/condense.sh --sync` |
+| Create new command | Create in `src/agent-src/commands/`, sync, `python3 src/scripts/condense.py --generate-tools` |
+| Delete a file | Delete from `src/` and `dist/agent-src/` |
+| Check what needs condensation | `bash src/scripts/condense.sh --changed` |
+| Mark file as condensed | `bash src/scripts/condense.sh --mark-done {path}` |
+| Verify everything is in sync | `bash src/scripts/condense.sh --check` |

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.