disinto-ops/sprints/agent-role-disambiguation.md

# 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 -->