Expand operations runbooks and add release checklist

README.md

@@ -90,6 +90,7 @@ Smart home safety defaults:
 - `HOME_PERMISSION_PROFILE=readonly` disables mutating `smart_home` actions but keeps `smart_home_state`.
 - Operational runbook: [`docs/operations/home-control-policy.md`](docs/operations/home-control-policy.md).
 - Integration runbook: [`docs/operations/integration-policy.md`](docs/operations/integration-policy.md).
+- Release checklist: [`docs/operations/release-checklist.md`](docs/operations/release-checklist.md).
 - Todoist integration:
   - `TODOIST_PERMISSION_PROFILE=readonly|control`
   - `readonly` allows `todoist_list_tasks` and denies `todoist_add_task`
@@ -99,6 +100,23 @@ Smart home safety defaults:
   - `off` denies `pushover_notify`
   - `allow` enables `pushover_notify`
 
+### First-Time Operator Checklist
+
+1. Copy `.env.example` to `.env`, then set required keys: `ANTHROPIC_API_KEY` and `ELEVENLABS_API_KEY`.
+2. If using integrations, set both values for each pair:
+   - `HASS_URL` and `HASS_TOKEN`
+   - `PUSHOVER_API_TOKEN` and `PUSHOVER_USER_KEY`
+3. Choose explicit permission profiles before first run:
+   - `HOME_PERMISSION_PROFILE=readonly` (recommended first boot)
+   - `TODOIST_PERMISSION_PROFILE=readonly`
+   - `NOTIFICATION_PERMISSION_PROFILE=off`
+4. Run local validation gates:
+   - `make check`
+   - `make test-faults`
+5. Start in simulation mode and confirm no startup warnings are emitted:
+   - `uv run python -m jarvis --sim --no-vision`
+6. If Home Assistant is enabled, run a `dry_run=true` smart-home request first before any live execute.
+
 ## Usage
 
 ```bash
@@ -147,6 +165,18 @@ Workflow linting and YAML hygiene run via
 Nightly soak coverage is scheduled in
 [`nightly-soak.yml`](.github/workflows/nightly-soak.yml).
 
+### CI Workflow Intent and Failure Routing
+
+| Workflow | Intent | Failure routing (first stop) |
+|---|---|---|
+| `ci.yml` / `lint` | Static checks (`ruff`) | `src/`, `tests/`, and Python style issues in the failing path |
+| `ci.yml` / `tests` | Full regression (`pytest`) | Failing test module and corresponding implementation area |
+| `ci.yml` / `faults` | Fault-injection taxonomy + error-path contract | `tests/test_tools.py` fault tests and `src/jarvis/tools/services.py` normalization paths |
+| `workflow-sanity.yml` | Workflow hygiene (`actionlint`, tabs, script executability/shebang) | `.github/workflows/*` and `scripts/*.sh` |
+| `shellcheck.yml` | Shell script linting | `scripts/*.sh` syntax/quoting/safety |
+| `security.yml` | Scheduled/PR CodeQL scan | Security findings in SARIF report; route by file ownership |
+| `nightly-soak.yml` | Long-run stability signal | `tests/test_main_audio.py -k soak`, audio/runtime regressions |
+
 ## Project Structure
 
 ```

TODO.md

@@ -117,11 +117,11 @@ Files: `tests/conftest.py`, `tests/test_tools.py`, `tests/test_*.py`
 - [x] `D01` Create external integrations runbook (Todoist/Pushover policy + troubleshooting).
 - [x] `D02` Update home-control runbook with redaction and cooldown semantics.
 - [x] `D03` Reconcile architecture diagram MCP/tool labels with current capabilities.
-- [ ] `D04` Add runbook section for CI workflow intent and failure routing.
-- [ ] `D05` Add operator checklist for first-time env setup validation.
-- [ ] `D06` Add troubleshooting matrix mapping common errors to likely fixes.
-- [ ] `D07` Add short section on audit location/rotation/redaction guarantees.
-- [ ] `D08` Add release checklist doc for safe rollout of policy changes.
+- [x] `D04` Add runbook section for CI workflow intent and failure routing.
+- [x] `D05` Add operator checklist for first-time env setup validation.
+- [x] `D06` Add troubleshooting matrix mapping common errors to likely fixes.
+- [x] `D07` Add short section on audit location/rotation/redaction guarantees.
+- [x] `D08` Add release checklist doc for safe rollout of policy changes.
 
 Files: `README.md`, `docs/operations/home-control-policy.md`, `docs/operations/integration-policy.md`, `docs/operations/release-checklist.md`
 

docs/operations/integration-policy.md

@@ -47,11 +47,29 @@ This runbook covers operational setup and policy behavior for Todoist and Pushov
   - `pushover_configured`
   - policy snapshot for todoist/notification profiles
 
-## 5) Security and Audit
-- Todoist and Pushover audits intentionally store metadata only.
-- Smart-home service payloads are sensitive-key redacted before audit write.
+## 5) Audit Location, Rotation, and Redaction Guarantees
+- Audit path: `~/.jarvis/audit.jsonl`
+- Rotation settings:
+  - `AUDIT_LOG_MAX_BYTES` default is `1000000`
+  - `AUDIT_LOG_BACKUPS` default is `3`
+  - Backups roll as `audit.jsonl.1` through `audit.jsonl.N`
+- Todoist and Pushover audits intentionally store metadata-only summaries.
+- Smart-home payload data is redacted by sensitive key token matching before audit write (`token`, `secret`, `code`, `pin`, `password`, etc.).
+- Redacted values are persisted as `***REDACTED***`.
 
-## 6) Troubleshooting
+## 6) Troubleshooting Matrix
+
+| Symptom | Likely cause | Operator action |
+|---|---|---|
+| `Todoist not configured. Set TODOIST_API_TOKEN.` | Missing/empty `TODOIST_API_TOKEN` | Set token in `.env` and restart process |
+| `Todoist authentication failed. Check TODOIST_API_TOKEN.` | Invalid or revoked Todoist token | Rotate token and retest with `todoist_list_tasks` |
+| `Pushover not configured. Set PUSHOVER_API_TOKEN and PUSHOVER_USER_KEY.` | One or both Pushover fields are missing | Set both values and restart process |
+| `Notification policy blocks pushover_notify` (tool denied) | `NOTIFICATION_PERMISSION_PROFILE=off` | Switch to `allow` if operationally approved |
+| `Todoist policy blocks todoist_add_task` (tool denied) | `TODOIST_PERMISSION_PROFILE=readonly` | Switch to `control` for write access |
+| `invalid_json` result from Todoist/Pushover path | Upstream payload shape changed or transient invalid response | Retry once, then inspect API response and update parser tests |
+| Repeated `http_error` / `network_client_error` | Upstream outage, DNS, connectivity, or timeout issue | Validate network path, check service status page, rerun `make test-faults` |
+
+## 7) Triage Flow
 1. Check credential env vars are set and non-empty.
 2. Check profile env vars:
    - `TODOIST_PERMISSION_PROFILE`

docs/operations/release-checklist.md

@@ -0,0 +1,68 @@
+# Release Checklist
+
+Use this checklist for policy or integration behavior changes before merging to `main` and before deploying to a live robot environment.
+
+## 1) Pre-merge Validation
+
+- [ ] `make check` passes locally.
+- [ ] `make test-faults` passes locally.
+- [ ] New/changed policy behavior has test coverage for:
+  - allow path
+  - deny path
+  - failure normalization path
+- [ ] `TODO.md` items touched in this release are updated (`[x]` / `[ ]`) to reflect current status.
+- [ ] Any new GitHub Action usage is pinned to a full commit SHA.
+
+## 2) Configuration Review
+
+- [ ] Required environment variables for changed integrations are documented in `README.md`.
+- [ ] Permission profiles are explicitly reviewed:
+  - `HOME_PERMISSION_PROFILE`
+  - `TODOIST_PERMISSION_PROFILE`
+  - `NOTIFICATION_PERMISSION_PROFILE`
+- [ ] Defaults are still safe for first boot (`readonly`/`off` where applicable).
+- [ ] Startup warning behavior remains accurate for incomplete configs.
+
+## 3) Audit and Safety Review
+
+- [ ] Audit output verified at `~/.jarvis/audit.jsonl`.
+- [ ] Sensitive fields are redacted in audit records (`***REDACTED***`).
+- [ ] Audit rotation tested or confirmed:
+  - `AUDIT_LOG_MAX_BYTES`
+  - `AUDIT_LOG_BACKUPS`
+- [ ] Destructive smart-home actions still require `confirm=true` where expected.
+- [ ] Dry-run paths (`dry_run=true`) were exercised before execute paths.
+
+## 4) CI and Workflow Health
+
+- [ ] `ci.yml` completes (`lint`, `tests`, and `faults` when applicable).
+- [ ] `workflow-sanity.yml` completes (actionlint + script checks).
+- [ ] `shellcheck.yml` completes for shell script changes.
+- [ ] `security.yml` has no new actionable CodeQL alerts for changed files.
+- [ ] Artifacts are present for test diagnostics:
+  - junit XML
+  - optional coverage XML (if manually requested)
+
+## 5) Rollout Steps
+
+1. Merge to `main` only after all required checks pass.
+2. Deploy and run an initial startup in simulation mode:
+   - `uv run python -m jarvis --sim --no-vision`
+3. Execute a low-risk live smoke test:
+   - read-only status path (`system_status`)
+   - integration read path (`todoist_list_tasks` if configured)
+   - smart-home dry-run path (if Home Assistant configured)
+4. Validate audit log writes for the smoke-test actions.
+
+## 6) Rollback Triggers and Actions
+
+Trigger rollback when any of the following occur:
+- Repeated `auth`, `http_error`, or `network_client_error` in a newly changed path.
+- Incorrect allow/deny policy behavior versus documented profiles.
+- Sensitive content appears in audit output.
+
+Rollback actions:
+1. Revert the release commit(s) from `main`.
+2. Re-run `make check` and `make test-faults`.
+3. Redeploy previous known-good revision.
+4. Capture incident notes and add missing regression tests before retrying release.