Consolidated addition, removal, and listing of locks under a single narratio locks command

docs/cli.md

@@ -23,9 +23,7 @@ Implemented commands:
 - `session validate`: run read-only preflight checks for a session.
 - `session init`: create local or remote `session.yml`.
 - `artifacts list`: list effective artifact source IDs.
-- `locks`: list effective archive promotion locks.
-- `lock`: add or update a remote session lock.
-- `unlock`: remove a remote session lock.
+- `locks`: list, add, and remove archive promotion locks.
 
 Unknown commands print usage and exit non-zero.
 
@@ -136,17 +134,17 @@ Valid stage names:
 - `--previous-session-id <value>`
 - `--remote`: check promoted remote object availability.
 
-### `locks`, `lock`, `unlock`
+### `locks`
 
-- `--config <path>`
-- `--campaign <path>`
-- `--session <path>`
-- `--session-id <value>`
-- `--previous-session-id <value>`
-- `lock <source>` positional source ID.
-- `lock --reason <text>` optional remote lock reason.
-- `lock --force` updates an existing remote lock.
-- `unlock <source>` positional source ID.
+- `--session-id <value>`: required for list, add, and remove.
+- `--config <path>`: optional explicit `pipeline.yml` path.
+- `--campaign <path>`: optional explicit `campaign.yml` path.
+- `--session <path>`: optional explicit `session.yml` path.
+- `--previous-session-id <value>`: optional session template value.
+- `add <source>`: add a remote lock for one artifact or transcript source.
+- `add --reason <text>`: record an optional remote lock reason.
+- `add --force`: update the reason for an existing remote lock.
+- `remove <source>`: remove one remote lock.
 
 ## Command Reference
 
@@ -291,25 +289,34 @@ narratio artifacts list [--config <pipeline.yml>] [--campaign <campaign.yml>] [-
 
 `--remote` checks promoted top-level object availability through the storage adapter.
 
-### `locks`, `lock`, and `unlock`
+### `locks`
 
 Purpose:
-- Inspect and mutate source-based archive promotion locks.
+- Inspect and mutate source-based archive promotion locks for one session.
 
 Syntax:
 
 ```bash
-narratio locks [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>]
-narratio lock [flags] <source>
-narratio unlock [flags] <source>
+narratio locks --session-id <id>
+narratio locks add --session-id <id> [--reason <text>] [--force] <source>
+narratio locks remove --session-id <id> <source>
 ```
 
 Behavior:
-- static locks from `pipeline.archive.locks` and remote locks from `{session_prefix}/locks.yml` are merged.
-- static locks win when sources duplicate remote locks.
-- `lock` writes or updates only remote locks.
-- `unlock` removes only remote locks and cannot remove static pipeline locks.
-- `lock --force` is required to update an existing remote lock reason.
+- `--session-id` is required for list, add, and remove.
+- optional `--config`, `--campaign`, and `--session` override default config discovery.
+- list mode prints effective locks from static `pipeline.archive.locks` and remote `{session_prefix}/locks.yml`.
+- `locks add` writes only the remote lock store and fails if the source is already locked by pipeline config.
+- `locks remove` removes only remote locks and cannot remove static pipeline locks.
+- `locks add --force` is required to update an existing remote lock reason.
+
+Examples:
+
+```bash
+narratio locks --session-id 2026-04-04
+narratio locks add --session-id 2026-04-04 --reason "manual transcript review" narratio.transcript.trimmed
+narratio locks remove --session-id 2026-04-04 narratio.transcript.trimmed
+```
 
 ### `run-stage`
 

docs/config.md

@@ -394,7 +394,7 @@ Remote mutable lock store:
 
 - path: `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/locks.yml`.
 - strict YAML shape: top-level `locks`, each with `source` and optional `reason`.
-- `narratio lock` and `narratio unlock` mutate only the remote lock store.
+- `narratio locks add` and `narratio locks remove` mutate only the remote lock store.
 - writes use existence checks plus `--force` for updates; they are not compare-and-swap atomic.
 
 Restore-related implications:

docs/operations.md

@@ -153,10 +153,10 @@ Archive promotion is explicit and source-based:
 
 Lock helper behavior:
 - `narratio locks --session-id <id>` lists effective static and remote locks.
-- `narratio lock <source> --session-id <id> --reason <text>` writes or updates a remote lock.
-- `narratio unlock <source> --session-id <id>` removes only a remote lock.
-- `lock --force` is required to update an existing remote lock reason.
-- `unlock` cannot remove static pipeline locks.
+- `narratio locks add --session-id <id> --reason <text> <source>` writes a remote lock.
+- `narratio locks add --session-id <id> --force --reason <text> <source>` updates an existing remote lock reason.
+- `narratio locks remove --session-id <id> <source>` removes only a remote lock.
+- `locks remove` cannot remove static pipeline locks.
 - remote lock writes check whether the lock store exists, but are not compare-and-swap atomic.
 
 ## Resume, retry, restore, and safe rerun behavior

docs/roadmap/operations.md

@@ -22,22 +22,22 @@ The operator helper command set is no longer conceptual. Current behavior is doc
 - `narratio artifacts list`
 - `narratio artifacts list --remote`
 - `narratio locks`
-- `narratio lock <source>`
-- `narratio unlock <source>`
+- `narratio locks add <source>`
+- `narratio locks remove <source>`
 
 ## Implemented Decisions
 
 - Helper output is text-only. No JSON schema exists yet.
 - `status` remains a top-level command.
 - `session validate`, `session init`, and `artifacts list` are nested helper commands.
-- `lock`, `unlock`, and `locks` are top-level commands.
+- `locks` is the single top-level command for listing, adding, and removing archive promotion locks.
 - Remote session initialization requires explicit `--remote`.
 - Local session initialization requires `--output`.
 - Remote artifact availability is opt-in with `artifacts list --remote`.
 - Mutable locks are source-based and stored at `{session_prefix}/locks.yml`.
 - The remote lock store uses strict YAML with top-level `locks`.
 - Static `pipeline.archive.locks` and remote locks are merged; static locks win on duplicate sources.
-- `unlock` removes only remote locks.
+- `locks remove` removes only remote locks.
 - Ordinary execution `--force` does not override locks.
 - Remote lock writes use existence checks and `--force` for updates; there is no compare-and-swap protection.
 
@@ -50,4 +50,3 @@ These are intentionally not implemented:
 - Rich remote artifact availability across historical run-local objects.
 - Session-lock acquisition for remote mutation helpers.
 - Broader campaign helper commands such as `campaign validate` or `campaign publish`.
-