# Roadmap: Session-Oriented CLI Cleanup

Status: Implemented

## Problem

Narratio's public CLI has accumulated too many top-level commands. Several
commands are session-scoped operator helpers, but they currently appear as
independent top-level verbs:

- `plan`
- `status`
- `restore`
- `artifacts list`
- `locks`
- `session validate`
- `session init`

This makes the command surface harder to learn because the CLI does not clearly
separate primary workflow actions from session inspection, initialization,
restore, and helper operations.

## Target Model

Keep primary workflow commands at top level:

- `run`
- `run-stage`
- `resume`
- `analyze`
- `publish`
- `clean`
- `session`

Keep `clean` top-level because it can operate on one session or all local
sessions and is a workspace maintenance command, not only a session helper.

Move session-scoped helper commands under `narratio session` and use positional
session identifiers:

- `narratio session init <session_id> [--remote|--output <path>] [--flags]`
- `narratio session validate <session_id> [--flags]`
- `narratio session status <session_id> [--flags]`
- `narratio session plan <session_id> [--flags]`
- `narratio session restore <session_id> [--flags]`
- `narratio session artifacts <session_id> [--remote] [--flags]`
- `narratio session locks <session_id> [--flags]`
- `narratio session locks add <session_id> <source> [--reason <text>] [--force] [--flags]`
- `narratio session locks remove <session_id> <source> [--flags]`

Update top-level workflow commands to use positional session identifiers:

- `narratio run <session_id> [--flags]`
- `narratio resume <session_id> [--flags]`
- `narratio analyze <session_id> [--flags]`
- `narratio publish <session_id> [--flags]`
- `narratio run-stage <stage> <session_id> [--flags]`

The positional session ID replaces `--session-id` as the primary public
interface. Existing `--config`, `--campaign`, `--session`, and
`--previous-session-id` flags remain available where they are meaningful.

## Command Mapping

| Current command | Target command |
| --- | --- |
| `narratio run --session-id <id>` | `narratio run <id>` |
| `narratio resume --session-id <id>` | `narratio resume <id>` |
| `narratio analyze --session-id <id>` | `narratio analyze <id>` |
| `narratio publish --session-id <id>` | `narratio publish <id>` |
| `narratio run-stage [flags] <stage> --session-id <id>` | `narratio run-stage <stage> <id> [flags]` |
| `narratio plan --session-id <id>` | `narratio session plan <id>` |
| `narratio status --session-id <id>` | `narratio session status <id>` |
| `narratio restore --session-id <id>` | `narratio session restore <id>` |
| `narratio artifacts list --session-id <id>` | `narratio session artifacts <id>` |
| `narratio locks --session-id <id>` | `narratio session locks <id>` |
| `narratio locks add --session-id <id> <source>` | `narratio session locks add <id> <source>` |
| `narratio locks remove --session-id <id> <source>` | `narratio session locks remove <id> <source>` |
| `narratio session validate --session-id <id>` | `narratio session validate <id>` |
| `narratio session init --session-id <id>` | `narratio session init <id>` |
| `narratio clean --session-id <id>` | `narratio clean <id>` |
| `narratio clean --all` | unchanged |

`clean` remains top-level, but its session-scoped form should also move from
`--session-id` to positional `<session_id>` for consistency.

## Compatibility Policy

This is a hard public CLI cleanup after the migration step lands.

During Step 1, old forms may remain as compatibility aliases to keep the
implementation reviewable. During Step 2, remove the old forms from command
dispatch, tests, docs, and examples:

- remove top-level `plan`;
- remove top-level `status`;
- remove top-level `restore`;
- remove top-level `artifacts`;
- remove top-level `locks`;
- remove `--session-id` from the public command syntax for session-aware
  commands.

Do not keep long-term deprecated aliases unless a later roadmap explicitly
chooses a compatibility window.

`status --manifest` does not fit the session-oriented command shape. Remove it
from the public CLI in this cleanup. If direct manifest inspection is needed
later, add a separate diagnostic command in a future roadmap rather than keeping
it as a special case in `session status`.

## Implementation Step 1: Add New Session-Oriented Interface

Status: Implemented

Add the target command forms while preserving current behavior internally.

Implementation requirements:

- Add positional session ID parsing helpers in `internal/app`.
- Keep the existing `loadCommandConfig` behavior and populate
  `config.SessionLoadOptions.SessionID` from the positional ID.
- Add or update command wrappers:
  - `Run(ctx, args, out)` parses `run <session_id>`.
  - `Resume(ctx, args, out)` parses `resume <session_id>`.
  - `Analyze(ctx, args, out)` parses `analyze <session_id>`.
  - `Publish(ctx, args, out)` parses `publish <session_id>`.
  - `RunStage(ctx, args, out)` parses `run-stage <stage> <session_id>`.
  - `Clean(ctx, args, out)` parses `clean <session_id>` and keeps
    `clean --all`.
- Extend `Session(ctx, args, out)` dispatch to support:
  - `init <session_id>`
  - `validate <session_id>`
  - `status <session_id>`
  - `plan <session_id>`
  - `restore <session_id>`
  - `artifacts <session_id>`
  - `locks <session_id>`
  - `locks add <session_id> <source>`
  - `locks remove <session_id> <source>`
- Keep storage access through the existing app-level object-store helper.
- Keep AWS SDK details behind storage adapters.
- Keep the runner, stages, manifest behavior, archive behavior, restore
  planning, lock semantics, and artifact catalog behavior unchanged.

Acceptance criteria:

- New forms execute the same code paths and produce equivalent results.
- Positional session ID mismatch with concrete local or remote `session.yml`
  fails through existing session identity checks.
- Remote session fallback still uses the positional session ID as the lookup
  value.
- Current command tests cover the new forms before old forms are removed.

## Implementation Step 2: Remove Old Public Forms

Status: Implemented

Remove compatibility aliases and make the session-oriented interface the only
documented and supported public CLI.

Implementation requirements:

- Remove top-level dispatch for:
  - `plan`
  - `status`
  - `restore`
  - `artifacts`
  - `locks`
- Remove `--session-id` flags from public session-aware commands.
- Keep `--previous-session-id` as an expected previous-session identity flag.
- Keep explicit `--session <path>` for loading a local concrete session file,
  but still require the positional session ID for commands that operate on a
  session.
- Remove `status --manifest`.
- Update usage text and invalid-command errors.
- Update `docs/cli.md` and `docs/operations.md` to use only the new forms.
- Update any roadmap docs that mention old helper command names.
- Update tests to expect old top-level helper commands and `--session-id` forms
  to fail.

Acceptance criteria:

- Top-level command list is exactly:
  - `run`
  - `run-stage`
  - `resume`
  - `analyze`
  - `publish`
  - `clean`
  - `session`
- All session-oriented commands use `narratio session <subcommand>
  <session_id> [--flags]`, except nested lock mutation forms, which use
  `narratio session locks add|remove <session_id> <source> [--flags]`.
- `clean <session_id>` and `clean --all` remain top-level.
- Current-behavior docs and tests no longer advertise `--session-id`.

## Test Guidance

Focused tests:

- `go test ./internal/app -run TestExecute -v`
- `go test ./internal/app -run 'Session|Status|Restore|Clean|Locks|Artifacts|Plan|RunStage|Analyze|Publish' -v`
- `go test ./internal/config -v`

Full validation:

- `go test ./...`

Test cases to add or update:

- `run <session_id>` loads local and remote sessions through the existing
  config path.
- `resume <session_id>`, `analyze <session_id>`, and `publish <session_id>`
  preserve current behavior.
- `run-stage <stage> <session_id>` preserves current run-stage output and
  force/artifact-selection behavior.
- `session plan <session_id>` replaces top-level `plan`.
- `session status <session_id>` replaces top-level session status.
- `session validate <session_id>` replaces `session validate --session-id`.
- `session init <session_id>` writes the same local or remote concrete
  `session.yml`.
- `session restore <session_id>` preserves restore planning/execution.
- `session artifacts <session_id> --remote` preserves promoted-output
  availability reporting.
- `session locks <session_id>`, `session locks add <session_id> <source>`, and
  `session locks remove <session_id> <source>` preserve static/remote lock
  semantics.
- `clean <session_id>` preserves session cleanup behavior, while `clean --all`
  remains unchanged.
- Old top-level helper commands fail after Step 2.
- `--session-id` fails after Step 2.
- `status --manifest` fails after Step 2.

## Documentation Guidance

Update only after implementation lands:

- `docs/cli.md`
- `docs/operations.md`
- any internal docs that list command names or examples

Keep planned behavior only in this roadmap until the command refactor is
implemented.

## Architecture Guardrails

- Keep Narratio explicit and stage-driven.
- Do not introduce a generic workflow or command framework abstraction.
- Reuse existing app command helpers where practical.
- Keep config loading strict and centralized.
- Keep storage details behind `storage.ObjectStore`.
- Keep secret-backed object-store construction in `internal/app`.
- Preserve manifest-driven resume and restore behavior.
- Treat command renaming as a public CLI contract change, not a runtime stage
  behavior change.