sprint: add design decisions section

sprints/agent-role-disambiguation.md

@@ -0,0 +1,101 @@
+# Sprint: agent-role-disambiguation
+
+## Vision issues
+- #851 — CLI word "agent" is overloaded — role vs hired forge user
+
+## What this enables
+A single, unambiguous meaning for "agent" across the CLI, docs, and TOML. `disinto agent` will no longer confuse users who just hired an agent via `hire-an-agent` and then get `Error: unknown agent` when they try to enable it by the same name. Future commands (rotate, remove, status) can be added without inheriting the ambiguity.
+
+## What exists today
+- `disinto hire-an-agent <name> <role>` creates a forge user (instance) — implemented in `lib/hire-agent.sh`, referenced in 6 files / 17 occurrences.
+- `disinto agent {enable,disable,status}` manages a hardcoded list of 6 roles (`dev, reviewer, gardener, architect, planner, predictor`) via state files in `state/.<role>-active` — implemented in `bin/disinto` lines 2540-2666.
+- `lib/guard.sh` checks state files to gate polling loops.
+- `[agents.X]` TOML sections and `agents-<name>` docker-compose services use "agent" to mean instance (matching `hire-an-agent` semantics).
+- `docker/agents/entrypoint.sh` uses `AGENT_ROLES` env var to route roles to scripts.
+- `docs/agents-llama.md` documents the hiring flow (8 references to `hire-an-agent`).
+- Existing sprint `agent-management-redesign.md` (#557) redesigns hiring UX but does not address the naming overload.
+
+## Complexity
+- 3 files changed substantively: `bin/disinto` (dispatch + help), `lib/guard.sh` (help text comment), `docs/agents-llama.md`
+- ~3 sub-issues
+- 95% gluecode (rename + alias), 5% greenfield (deprecation warning logic)
+
+## Risks
+- **Script breakage:** Users or automation calling `disinto agent enable dev` will break without a deprecation shim. Mitigated by alias + warning for one release cycle.
+- **Incomplete rename:** Missing a reference in help text or docs leaves partial ambiguity. Mitigated by grep-sweep acceptance criterion.
+- **Sprint overlap with #557:** The agent-management-redesign sprint touches the same CLI surface. This sprint should land first so #557 builds on clean terminology.
+
+## Cost — new infra to maintain
+- One deprecation alias in `bin/disinto` (temporary — removed after one release cycle)
+- No new services, scheduled tasks, formulas, or agent roles
+
+## Recommendation
+Worth it. This is a small, low-risk naming fix that unblocks cleaner UX for future agent management work (#557, #845-#847). The overload is already causing user-facing errors. Option A ("agent" = instance, rename role subcommand to `disinto role`) aligns with existing TOML (`[agents.X]`) and container naming (`agents-<name>`), minimizing total churn.
+
+## Design decisions
+
+<!-- Status: AWAITING ANSWERS — questions posted 2026-04-19 -->
+
+### Q1: New subcommand name
+What replaces `disinto agent {enable,disable,status}`?
+- A) `disinto role` — matches `AGENT_ROLES` naming, short, clear
+- B) `disinto service` — emphasizes polling-loop service aspect
+- C) `disinto module` — neutral, less intuitive for enable/disable
+
+### Q2: Internal variable rename scope
+Rename CLI surface only, or also internal identifiers?
+- A) CLI only — keep `AGENT_ROLES`, state files, function names unchanged
+- B) Full rename — `AGENT_ROLES`→`ACTIVE_ROLES`, state files, function names
+
+### Q3: Deprecation shim removal timing
+When does the old `disinto agent` alias get removed?
+- A) After #557 (agent-management-redesign) merges
+- B) Calendar-based: 30 days after merge
+- C) Never — keep alias permanently
+
+## Sub-issues
+
+<!-- filer:begin -->
+- id: rename-agent-subcommand-to-role
+  title: "vision(#851): rename `disinto agent` subcommand to `disinto role`"
+  labels: [backlog]
+  depends_on: []
+  body: |
+    ## Goal
+    Rename the `disinto agent {enable,disable,status}` CLI subcommand to `disinto role {enable,disable,status}` so "agent" consistently means a hired forge user (instance) across the CLI.
+
+    ## Acceptance criteria
+    - [ ] `disinto role enable dev`, `disinto role disable dev`, `disinto role status` work identically to the old `disinto agent` equivalents
+    - [ ] `disinto role enable --all` and `disinto role disable --all` work
+    - [ ] `disinto agent enable dev` still works but prints a deprecation warning to stderr: `Warning: 'disinto agent' is deprecated, use 'disinto role' instead`
+    - [ ] `disinto --help` shows `role` as the primary subcommand and does not list `agent` as a top-level subcommand for role management
+    - [ ] `grep -r 'disinto agent enable\|disinto agent disable\|disinto agent status' bin/ lib/ docs/` returns zero hits outside the deprecation shim itself
+
+- id: update-docs-agent-terminology
+  title: "vision(#851): update docs to disambiguate agent vs role"
+  labels: [backlog]
+  depends_on: [rename-agent-subcommand-to-role]
+  body: |
+    ## Goal
+    Update all user-facing documentation so "agent" means hired forge user (instance) and "role" means the abstract capability (dev, reviewer, gardener, etc.).
+
+    ## Acceptance criteria
+    - [ ] `docs/agents-llama.md` uses "role" when referring to enable/disable and "agent" only for the hired instance
+    - [ ] `AGENTS.md` agent table and label conventions use consistent terminology
+    - [ ] `lib/guard.sh` inline comments updated
+    - [ ] `disinto --help` full output uses "role" for enable/disable, "agent" for hire-an-agent
+    - [ ] No doc sentence uses "agent" to mean both instance and role in the same paragraph
+
+- id: remove-agent-deprecation-shim
+  title: "vision(#851): remove deprecated `disinto agent` alias after transition period"
+  labels: [backlog]
+  depends_on: [rename-agent-subcommand-to-role]
+  body: |
+    ## Goal
+    Remove the `disinto agent` → `disinto role` deprecation alias after one release cycle, completing the rename.
+
+    ## Acceptance criteria
+    - [ ] `disinto agent enable dev` returns a clear error: `Unknown command 'agent'. Did you mean 'role'?`
+    - [ ] No deprecation shim code remains in `bin/disinto`
+    - [ ] CHANGELOG or commit message notes the breaking change
+<!-- filer:end -->